├── README.md ├── config └── ngx_http_hello_world_module.c /README.md: -------------------------------------------------------------------------------- 1 | # Hello World Module for Nginx 2 | 3 | ## Introduction 4 | 5 | This module serves as a learning exercise for me, and hopefully for 6 | others too, when doing [Nginx](http://nginx.org) module development. 7 | 8 | I [stole](http://dominicfallows.com/2011/02/20/hello-world-nginx-module-3/) 9 | the code and added some notes using mostly Evan Miller's 10 | [Nginx Module Development Guide](http://www.evanmiller.org/nginx-modules-guide.html). Also 11 | helpful is the 12 | [translation](http://antoine.bonavita.free.fr/nginx_mod_dev_en.html) 13 | of Vhalery Kholodov's 14 | [Nginx Module Guide](http://www.grid.net.ru/nginx/nginx-modules.html) 15 | done by [Antoine Bonavita](http://antoine.bonavita.free.fr/) that also 16 | mantains a [Nginx Discovery](http://www.nginx-discovery.com/) blog to 17 | document his journey on Nginx module development. 18 | 19 | ## Installation 20 | 21 | 1. Configure Nginx adding this module with: 22 | 23 | Static Module : ./configure (...) --add-module=/path/to/nginx-hello-world-module 24 | Dynamic Module: ./configure (...) --add-dynamic-module=/path/to/nginx-hello-world-module 25 | 26 | 2. Build Nginx as usual with `make`. 27 | 28 | 3. Configure the module. There's only one directive `hello_world` 29 | that is supported in the **location** context only. 30 | 31 | Example: 32 | 33 | location = /test { 34 | 35 | hello_world; 36 | 37 | } 38 | 39 | Now doing something like: 40 | 41 | curl -i http://example.com/test 42 | 43 | should return the **hello world** string as the response body. 44 | 45 | ## Further reading 46 | 47 | * English: You can go to the [Nginx Planet](http://planet.nginx.org/) 48 | and get a lot of Nginx related information. 49 | 50 | * Russian: The [Habrahabr Nginx Blog](habrahabr.ru/blogs/nginx/) a 51 | treasure trove of Nginx related discussions. Use google translate 52 | or Babelfish if you don't read Russian. 53 | 54 | ## TODO 55 | 56 | 1. Add an argument to the `hello_world` directive specifying the 57 | language. For example: 58 | 59 | * en: hello world 60 | 61 | * fr: bounjour monde 62 | 63 | * pt: olá mundo 64 | 65 | * es: hola mundo 66 | 67 | 2. Make the `hello_world` directive be also defined in the **if in 68 | location** context (`NGX_HTTP_LIF_CONF`) in 69 | `ngx_http_config.h`. Which implies defining a **merge 70 | configuration** function. 71 | 72 | 3. Document everything with 73 | [Doxygen](https://secure.wikimedia.org/wikipedia/en/wiki/Doxygen) 74 | linking the relevant header and source files from the Nginx core. 75 | -------------------------------------------------------------------------------- /config: -------------------------------------------------------------------------------- 1 | ngx_addon_name=ngx_http_hello_world_module 2 | 3 | if test -n "$ngx_module_link"; then 4 | ngx_module_type=HTTP 5 | ngx_module_name=ngx_http_hello_world_module 6 | ngx_module_srcs="$ngx_addon_dir/ngx_http_hello_world_module.c" 7 | . auto/module 8 | else 9 | HTTP_MODULES="$HTTP_MODULES ngx_http_hello_world_module" 10 | NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_hello_world_module.c" 11 | fi 12 | -------------------------------------------------------------------------------- /ngx_http_hello_world_module.c: -------------------------------------------------------------------------------- 1 | /** 2 | * @file ngx_http_hello_world_module.c 3 | * @author António P. P. Almeida 4 | * @date Wed Aug 17 12:06:52 2011 5 | * 6 | * @brief A hello world module for Nginx. 7 | * 8 | * @section LICENSE 9 | * 10 | * Copyright (C) 2011 by Dominic Fallows, António P. P. Almeida 11 | * 12 | * Permission is hereby granted, free of charge, to any person obtaining a copy 13 | * of this software and associated documentation files (the "Software"), to deal 14 | * in the Software without restriction, including without limitation the rights 15 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 16 | * copies of the Software, and to permit persons to whom the Software is 17 | * furnished to do so, subject to the following conditions: 18 | * The above copyright notice and this permission notice shall be included in 19 | * all copies or substantial portions of the Software. 20 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 21 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 22 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 23 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 24 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 25 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 26 | * THE SOFTWARE. 27 | * 28 | */ 29 | #include 30 | #include 31 | #include 32 | 33 | 34 | #define HELLO_WORLD "hello world\r\n" 35 | 36 | static char *ngx_http_hello_world(ngx_conf_t *cf, ngx_command_t *cmd, void *conf); 37 | static ngx_int_t ngx_http_hello_world_handler(ngx_http_request_t *r); 38 | 39 | /** 40 | * This module provided directive: hello world. 41 | * 42 | */ 43 | static ngx_command_t ngx_http_hello_world_commands[] = { 44 | 45 | { ngx_string("hello_world"), /* directive */ 46 | NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS, /* location context and takes 47 | no arguments*/ 48 | ngx_http_hello_world, /* configuration setup function */ 49 | 0, /* No offset. Only one context is supported. */ 50 | 0, /* No offset when storing the module configuration on struct. */ 51 | NULL}, 52 | 53 | ngx_null_command /* command termination */ 54 | }; 55 | 56 | /* The hello world string. */ 57 | static u_char ngx_hello_world[] = HELLO_WORLD; 58 | 59 | /* The module context. */ 60 | static ngx_http_module_t ngx_http_hello_world_module_ctx = { 61 | NULL, /* preconfiguration */ 62 | NULL, /* postconfiguration */ 63 | 64 | NULL, /* create main configuration */ 65 | NULL, /* init main configuration */ 66 | 67 | NULL, /* create server configuration */ 68 | NULL, /* merge server configuration */ 69 | 70 | NULL, /* create location configuration */ 71 | NULL /* merge location configuration */ 72 | }; 73 | 74 | /* Module definition. */ 75 | ngx_module_t ngx_http_hello_world_module = { 76 | NGX_MODULE_V1, 77 | &ngx_http_hello_world_module_ctx, /* module context */ 78 | ngx_http_hello_world_commands, /* module directives */ 79 | NGX_HTTP_MODULE, /* module type */ 80 | NULL, /* init master */ 81 | NULL, /* init module */ 82 | NULL, /* init process */ 83 | NULL, /* init thread */ 84 | NULL, /* exit thread */ 85 | NULL, /* exit process */ 86 | NULL, /* exit master */ 87 | NGX_MODULE_V1_PADDING 88 | }; 89 | 90 | /** 91 | * Content handler. 92 | * 93 | * @param r 94 | * Pointer to the request structure. See http_request.h. 95 | * @return 96 | * The status of the response generation. 97 | */ 98 | static ngx_int_t ngx_http_hello_world_handler(ngx_http_request_t *r) 99 | { 100 | ngx_buf_t *b; 101 | ngx_chain_t out; 102 | 103 | /* Set the Content-Type header. */ 104 | r->headers_out.content_type.len = sizeof("text/plain") - 1; 105 | r->headers_out.content_type.data = (u_char *) "text/plain"; 106 | 107 | /* Allocate a new buffer for sending out the reply. */ 108 | b = ngx_pcalloc(r->pool, sizeof(ngx_buf_t)); 109 | 110 | /* Insertion in the buffer chain. */ 111 | out.buf = b; 112 | out.next = NULL; /* just one buffer */ 113 | 114 | b->pos = ngx_hello_world; /* first position in memory of the data */ 115 | b->last = ngx_hello_world + sizeof(ngx_hello_world) - 1; /* last position in memory of the data */ 116 | b->memory = 1; /* content is in read-only memory */ 117 | b->last_buf = 1; /* there will be no more buffers in the request */ 118 | 119 | /* Sending the headers for the reply. */ 120 | r->headers_out.status = NGX_HTTP_OK; /* 200 status code */ 121 | /* Get the content length of the body. */ 122 | r->headers_out.content_length_n = sizeof(ngx_hello_world) - 1; 123 | ngx_http_send_header(r); /* Send the headers */ 124 | 125 | /* Send the body, and return the status code of the output filter chain. */ 126 | return ngx_http_output_filter(r, &out); 127 | } /* ngx_http_hello_world_handler */ 128 | 129 | /** 130 | * Configuration setup function that installs the content handler. 131 | * 132 | * @param cf 133 | * Module configuration structure pointer. 134 | * @param cmd 135 | * Module directives structure pointer. 136 | * @param conf 137 | * Module configuration structure pointer. 138 | * @return string 139 | * Status of the configuration setup. 140 | */ 141 | static char *ngx_http_hello_world(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) 142 | { 143 | ngx_http_core_loc_conf_t *clcf; /* pointer to core location configuration */ 144 | 145 | /* Install the hello world handler. */ 146 | clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module); 147 | clcf->handler = ngx_http_hello_world_handler; 148 | 149 | return NGX_CONF_OK; 150 | } /* ngx_http_hello_world */ 151 | --------------------------------------------------------------------------------