link: The Application dynamic linking with Nginx
Installation
You can install this module in any RHEL-based distribution, including, but not limited to:
- RedHat Enterprise Linux 7, 8, 9 and 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 and Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-link
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-link
Enable the module by adding the following at the top of /etc/nginx/nginx.conf:
load_module modules/ngx_http_link_func_module.so;
This document describes nginx-module-link v3.2.4 released on Oct 13 2020.
nginx-link-function
The Application dynamic linking with Nginx
Introduction
nginx-link-function is a nginx module which provides dynamic linking to your application in server context and call the function of your application in location directive.You could direct link your C/C++ application (or any other which accept dynamic linking) to nginx server.
How it works
Usage
## nginx.conf
server {
listen 8888;
...
ngx_link_func_lib "/path/to/your/libcfuntest.so";
...
...
location = /testCFunGreeting {
ngx_link_func_call "my_app_simple_get_greeting";
}
}
server {
listen 8989;
aio threads;
...
ngx_link_func_lib "/path/to/your/libcfuntest.so"; # sharing data memory with server 1 if the path are same with server 1
...
...
location = /testCFunGreeting {
ngx_link_func_call "my_app_simple_get_greeting"
}
}
server {
listen 8999;
aio threads;
...
ngx_link_func_lib "/path/to/your/libcfuntest2.so"; # another application
...
...
location = /testPost {
add_header Allow "GET, POST, HEAD" always;
if ( $request_method !~ ^(POST)$ ) {
return 405;
}
ngx_link_func_call "my_2nd_app_simple_get_token";
}
}
server {
listen 9888;
aio threads;
...
## Download application from cloud repo e.g. ngx_link_func_download_link_lib <download_link> <dest_link_file>
ngx_link_func_download_link_lib "http://abc.com/repos/libcfuntest.so" "/etc/nginx/libcfuntest3.so"
...
...
location = /testPost {
add_header Allow "GET, POST, HEAD" always;
if ( $request_method !~ ^(POST)$ ) {
return 405;
}
ngx_link_func_call "my_3rd_app_simple_get_token";
}
}
server {
listen 9898;
aio threads;
...
## Download application from cloud repo with extra header e.g. ngx_link_func_download_link_lib <download_link> <headers> <dest_link_file>
ngx_link_func_download_link_lib "https://abc.com/repos/libcfuntest.so" "Accept-Language:en_US\r\nAuthorization:Bearer KA.eyJ2ZXJzaadlasdlaldhjHJ2h3ldjklsjaklcjkljasdklcmasaskdaJxdkL3ftjM\r\n" "/etc/nginx/libcfuntest4.so"
...
...
location = /testPost {
add_header Allow "GET, POST, HEAD" always;
if ( $request_method !~ ^(POST)$ ) {
return 405;
}
ngx_link_func_call "my_other_app_simple_get_token";
}
}
Interface that expose to client application
This is the interface that you can use to get more details from nginx server, it all inside the ngx_link_func_module.h.
#define ngx_link_func_content_type_plaintext "text/plain"
#define ngx_link_func_content_type_html "text/html; charset=utf-8"
#define ngx_link_func_content_type_json "application/json"
#define ngx_link_func_content_type_jsonp "application/javascript"
#define ngx_link_func_content_type_xformencoded "application/x-www-form-urlencoded"
typedef struct {
char *req_args; // Uri Args
u_char *req_body; // Request Body
size_t req_body_len; // length of body
void *shared_mem;
/* internal */
void* __r__;
void* __pl__;
void* __log__;
} ngx_link_func_ctx_t;
extern void ngx_link_func_log_debug(ngx_link_func_ctx_t *ctx, const char* msg);
extern void ngx_link_func_log_info(ngx_link_func_ctx_t *ctx, const char* msg);
extern void ngx_link_func_log_warn(ngx_link_func_ctx_t *ctx, const char* msg);
extern void ngx_link_func_log_err(ngx_link_func_ctx_t *ctx, const char* msg);
extern u_char* ngx_link_func_get_header(ngx_link_func_ctx_t *ctx, const char*key);
extern void* ngx_link_func_get_query_param(ngx_link_func_ctx_t *ctx, const char *key);
extern void* ngx_link_func_palloc(ngx_link_func_ctx_t *ctx, size_t size);
extern void* ngx_link_func_pcalloc(ngx_link_func_ctx_t *ctx, size_t size);
extern void ngx_link_func_write_resp(
ngx_link_func_ctx_t *ctx,
uintptr_t status_code,
const char* status_line,
const char* content_type,
const char* resp_content,
size_t resp_len
);
// Shared Memory and Cache Scope
extern void ngx_link_func_shmtx_lock(void *shared_mem);
extern void ngx_link_func_shmtx_unlock(void *shared_mem);
extern void* ngx_link_func_shm_alloc(void *shared_mem, size_t size);
extern void ngx_link_func_shm_free(void *shared_mem, void *ptr);
extern void* ngx_link_func_cache_get(void *shared_mem, const char* key);
extern void* ngx_link_func_cache_put(void *shared_mem, const char* key, void* value);
extern void* ngx_link_func_cache_new(void *shared_mem, const char* key, size_t size);
extern void ngx_link_func_cache_remove(void *shared_mem, const char* key);
Interface break down details
malloc/calloc from nginx pool
void* ngx_link_func_palloc(ngx_link_func_ctx_t *ctx, size_t size);
void* ngx_link_func_pcalloc(ngx_link_func_ctx_t *ctx, size_t size);
get the request header parameter from
extern u_char* ngx_link_func_get_header(ngx_link_func_ctx_t *ctx, const char*key);
get the uri args
ctx->req_args;
get the query parameter
extern void* ngx_link_func_get_query_param(ngx_link_func_ctx_t *ctx, const char *key);
get the request body
ctx->req_body;
get the request body length
ctx->req_body_len;
loggin to nginx server
extern void ngx_link_func_log_debug(ngx_link_func_ctx_t *ctx, const char* msg);
extern void ngx_link_func_log_info(ngx_link_func_ctx_t *ctx, const char* msg);
extern void ngx_link_func_log_warn(ngx_link_func_ctx_t *ctx, const char* msg);
extern void ngx_link_func_log_err(ngx_link_func_ctx_t *ctx, const char* msg);
Response out
extern void ngx_link_func_write_resp(
ngx_link_func_ctx_t *ctx,
uintptr_t status_code, // Status code
const char* status_line, // Status line
const char* content_type, // Response content type
const char* resp_content, // Response content
size_t resp_len // Response content length
);
Sample Application Development
Feel free to clone a sample project at
link function google direction linkfunc-jwt-auth
#include <stdio.h>
#include <ngx_link_func_module.h>
/*** build the program as .so library and copy to the preferred place for nginx to link this library ***/
/*** gcc -shared -o libcfuntest.so -fPIC cfuntest.c ***/
/*** cp libcfuntest.so /etc/nginx/ ***/
int is_service_on = 0;
void ngx_link_func_init_cycle(ngx_link_func_cycle_t* cycle) {
ngx_link_func_cyc_log(info, cycle, "%s", "starting application");
is_service_on=1;
}
void my_app_simple_get_greeting(ngx_link_func_ctx_t *ctx) {
ngx_link_func_log_info(ctx, "Calling back and log from my_app_simple_get");
ngx_link_func_write_resp(
ctx,
200,
"200 OK",
"text/plain",
"greeting from ngx_link_func testing",
sizeof("greeting from ngx_link_func testing")-1
);
}
void my_app_simple_get_args(ngx_link_func_ctx_t *ctx) {
ngx_link_func_log_info(ctx, "Calling back and log from my_app_simple_get_args");
if(ctx->req_args) {
ngx_link_func_write_resp(
ctx,
200,
"200 OK",
"text/plain",
ctx->req_args,
strlen(ctx->req_args)
);
} else {
ngx_link_func_write_resp(
ctx,
204,
"",
"text/plain",
NULL,
0
);
}
}
void my_app_simple_get_token_args(ngx_link_func_ctx_t *ctx) {
ngx_link_func_log_info(ctx, "Calling back and log from my_app_simple_get_token_args");
char * tokenArgs = (char*)ngx_link_func_get_query_param(ctx, "token");
if (! tokenArgs) {
ngx_link_func_write_resp(
ctx,
401,
"401 unauthorized",
"text/plain",
"Token Not Found",
sizeof("Token Not Found")-1
);
} else {
ngx_link_func_write_resp(
ctx,
401,
"401 unauthorized",
"text/plain",
tokenArgs,
strlen(tokenArgs)
);
}
}
void my_app_simple_post(ngx_link_func_ctx_t *ctx) {
ngx_link_func_log_info(ctx, "Calling back and log from my_app_simple_post");
ngx_link_func_write_resp(
ctx,
202,
"202 Accepted and Processing",
"text/plain",
NULL,
0
);
}
void my_app_simple_get_no_resp(ngx_link_func_ctx_t *ctx) {
ngx_link_func_log_info(ctx, "Calling back and log from my_app_simple_get_no_resp");
// return 404
}
void ngx_link_func_exit_cycle(ngx_link_func_cycle_t* cyc) {
ngx_link_func_cyc_log(info, cyc, "%s\n", "Shutting down/reloading the Application");
is_service_on = 0;
}
Noted:
The function init and exit cycle are reserved function when started the nginx, it will call init cycle function, when stop/reload nginx, it will call exit cycle function.
void ngx_link_func_init_cycle(ngx_link_func_cycle_t* cyc){}
void ngx_link_func_exit_cycle(ngx_link_func_cycle_t* cyc){}
Log Level
The log can be called, the logged message will be store where you config error log in nginx.conf
ngx_link_func_log_info(ctx, "This is info direct message");
ngx_link_func_log(info, ctx, "%s", "This is info with formatted message");
ngx_link_func_log_debug(ctx, "This is debug direct message");
ngx_link_func_log(debug, ctx, "%s", "This is debug with formatted message");
ngx_link_func_log_info(ctx, "%s", "This is info with formatted message"); // Wrong format
ngx_link_func_log_debug(ctx, "%s", "This is info with formatted message"); // Wrong format
provide ca-cert to download your app(.so)?? please embedded this in your nginx.conf's server context.
ngx_link_func_ca_cert "/etc/ssl/certs/ca-cert.crt"
ngx_link_func_download_link_lib "https://abc.com/repos/libcfuntest.so" "/etc/nginx/libcfuntest4.so"
provide ca-cert and extra header to download your app(.so)?? please embedded this in your nginx.conf's server context.
ngx_link_func_ca_cert "/etc/ssl/certs/ca-cert.crt"
ngx_link_func_download_link_lib "https://abc.com/repos/libcfuntest.so" "Accept-Language:en_US\r\nAuthorization:Bearer KA.eyJ2ZXJzaadlasdlaldhjHJ2h3ldjklsjaklcjkljasdklcmasaskdaJxdkL3ftjM\r\n" "/etc/nginx/libcfuntest4.so"
Test
It depends on nginx test suite libs, please refer test-nginx for installation.
cd /path/to/nginx-link-function
export PATH=/path/to/nginx-dirname:$PATH
sudo prove -r t/
Support
Please raise an issue and I will fixed it as soon as I can
Alternatively, you may email to minikawoon2017@gmail.com
Wiki
Check out wiki for more details
GitHub
You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-link.