NGINX JavaScript, también conocido como NJS, es un módulo dinámico para NGINX que permite la extensión de la funcionalidad integrada utilizando la sintaxis familiar de JavaScript. El lenguaje NJS es un subconjunto de JavaScript, compatible con ES5 (ECMAScript 5.1 Strict Variant) con algunos ES6 (ECMAScript 6) y extensiones más recientes. Ver compatibilidad para más detalles.
NGINX JavaScript se proporciona como dos módulos dinámicos para NGINX (ngx_http_js_module y ngx_stream_js_module) y se puede agregar a cualquier instalación NGINX Open Source o NGINX Plus compatible sin necesidad de volver a compilar.
El módulo NJS permite a los administradores de NGINX:
Vea ejemplos y nuestros diversos proyectos desarrollados con NJS:
Extiende la funcionalidad de NGINX Plus para comunicarse directamente con proveedores de identidad compatibles con OIDC, autenticando usuarios y autorizando el contenido entregado por NGINX Plus.
Implementación de referencia de NGINX Plus como proveedor de servicios para autenticación SAML.
Expone el punto final de métricas de Prometheus directamente desde NGINX Plus.
Consejo
NJS también se puede utilizar con el servidor de aplicaciones de la Unidad NGINX. Obtenga más información sobre la API de control de la unidad NGINX y cómo definir llamadas a funciones con NJS.
Siga estos pasos para descargar e instalar archivos binarios NGINX y NGINX JavaScript Linux precompilados. También puede optar por crear el módulo localmente a partir del código fuente.
Siga esta guía para agregar el repositorio oficial de paquetes NGINX a su sistema e instalar NGINX Open Source. Si ya tiene NGINX Open Source o NGINX Plus instalado, omita la parte de instalación de NGINX en el último paso.
Una vez que se haya aprovisionado el repositorio, puede instalar NJS emitiendo el siguiente comando:
sudo apt install nginx-module-njssudo yum install nginx-module-njssudo apk add nginx-module-njs@nginxsudo zypper install nginx-module-njsConsejo
El repositorio de paquetes incluye un módulo alternativo que habilita símbolos de depuración. Aunque no se recomienda para entornos de producción, este módulo puede resultar útil al desarrollar configuraciones basadas en NJS. Para descargar e instalar la versión de depuración del módulo, reemplace el nombre del módulo en el comando anterior con nginx-module-njs-dbg .
Los scripts de instalación del paquete instalan dos módulos, que admiten NGINX http y contextos stream .
ngx_http_js_module
Este módulo NJS permite la manipulación de datos transmitidos a través de HTTP.
ngx_stream_js_module
Este módulo NJS permite la manipulación de datos transmitidos a través de protocolos de flujo como TCP y UDP.
De forma predeterminada, ambos módulos se instalan en el directorio /etc/nginx/modules .
El uso de NJS implica habilitar el módulo, agregar archivos JavaScript con funciones definidas e invocar funciones exportadas en archivos de configuración NGINX.
NGINX JavaScript es un módulo para NGINX Open Source o NGINX Plus. Si aún no lo ha hecho, siga estos pasos para instalar NGINX Open Source o NGINX Plus. Una vez instalada, asegúrese de que la instancia de NGINX se esté ejecutando y pueda responder a las solicitudes HTTP.
Emita el siguiente comando para iniciar NGINX:
sudo nginxcurl -I 127.0.0.1Deberías ver la siguiente respuesta:
HTTP/1.1 200 OK
Server: nginx/1.25.5 Una vez instalado, uno (o ambos) módulo(s) NJS debe(n) incluirse en el archivo de configuración de NGINX. En la mayoría de los sistemas, el archivo de configuración de NGINX se encuentra en /etc/nginx/nginx.conf de forma predeterminada.
sudo vi /etc/nginx/nginx.confUtilice la directiva load_module en el contexto de nivel superior ("principal") para habilitar uno (o ambos) módulo(s).
load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so; Los archivos de script NJS normalmente se denominan con una extensión .js y se colocan en el directorio /etc/nginx/njs/ . Por lo general, se componen de funciones que luego se exportan, haciéndolas disponibles en los archivos de configuración de NGINX.
NJS proporciona una colección de objetos con métodos y propiedades asociados que no forman parte de las definiciones de ECMAScript. Vea la referencia completa a estos objetos y cómo se pueden utilizar para ampliar y personalizar aún más NGINX.
A continuación se muestra un ejemplo básico de "Hola mundo".
La función hello en este archivo devuelve un código de respuesta de estado HTTP 200 OK junto con la cadena "¡Hola mundo!", seguido de un salto de línea. Luego, la función se exporta para usarla en un archivo de configuración NGINX.
Agregue este archivo al directorio /etc/nginx/njs :
function hello ( r ) {
r . return ( 200 , "Hello world!n" ) ;
}
export default { hello } Modificamos nuestra configuración de NGINX ( /etc/nginx/nginx.conf ) para importar el archivo JavaScript y ejecutar la función en circunstancias específicas.
# Load the ngx_http_js_module module
load_module modules/ngx_http_js_module.so;
events {}
http {
# Set the path to our njs JavaScript files
js_path "/etc/nginx/njs/" ;
# Import our JavaScript file into the variable "main"
js_import main from http/hello.js;
server {
listen 80 ;
location / {
# Execute the "hello" function defined in our JavaScript file on all HTTP requests
# and respond with the contents of our function.
js_content main.hello;
}
}
}Para obtener una lista completa de las directivas njs, consulte las páginas de documentación de los módulos ngx_http_js_module y ngx_stream_js_module.
Consejo
Puede encontrar una versión más detallada de este y otros ejemplos en el repositorio oficial de ejemplos de njs.
NGINX JavaScript se instala con una utilidad de interfaz de línea de comandos. La interfaz se puede abrir como un shell interactivo o usarse para procesar la sintaxis de JavaScript a partir de archivos predefinidos o entradas estándar. Dado que la utilidad se ejecuta de forma independiente, los objetos específicos de NGINX, como HTTP y Stream, no están disponibles en su tiempo de ejecución.
$ njs
>> globalThis
global {
njs: njs {
version : '0.8.4'
} ,
global : [ Circular ] ,
process : process {
argv : [ '/usr/bin/njs' ] ,
env : {
PATH : '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' ,
HOSTNAME : 'f777c149d4f8' ,
TERM : 'xterm' ,
NGINX_VERSION : '1.25.5' ,
NJS_VERSION : '0.8.4' ,
PKG_RELEASE : '1~buster' ,
HOME : '/root'
}
} ,
console : {
log : [ Function : native ] ,
dump : [ Function : native ] ,
time : [ Function : native ] ,
timeEnd : [ Function : native ]
} ,
print : [ Function : native ]
}
>>$ echo " 2**3 " | njs -q
8Los siguientes pasos se pueden utilizar para crear NGINX JavaScript como un módulo dinámico que se integrará en NGINX o un binario independiente para usarlo como una utilidad de interfaz de línea de comandos.
Importante
Para construir el módulo para usar con NGINX, también necesitará clonar, configurar y construir NGINX siguiendo los pasos descritos en este documento.
La mayoría de las distribuciones de Linux requerirán la instalación de varias dependencias para poder compilar NGINX y NGINX JavaScript. Las siguientes instrucciones son específicas del administrador de paquetes apt , ampliamente disponible en la mayoría de las distribuciones Ubuntu/Debian y sus derivados.
sudo apt install gcc makesudo apt install libpcre3-dev zlib1g-dev libssl-dev libxml2-dev libxslt-devPara compilar con QuickJS, también necesitará compilar la biblioteca QuickJS:
git clone https://github.com/bellard/quickjs
cd quickjs
CFLAGS= ' -fPIC ' make libquickjs.aAdvertencia
Este es el conjunto mínimo de bibliotecas de dependencia necesarias para crear NGINX y NJS. Es posible que se requieran otras dependencias si elige compilar NGINX con módulos adicionales. Supervise el resultado del comando configure que se analiza en las siguientes secciones para obtener información sobre qué módulos pueden faltar.
Utilizando su método preferido, clone el repositorio de JavaScript NGINX en su directorio de desarrollo. Consulte Clonar un repositorio de GitHub para obtener ayuda adicional.
https://github.com/nginx/njs.gitLos siguientes pasos son opcionales y solo son necesarios si elige crear NJS como una utilidad independiente.
Para utilizar el shell interactivo NJS, deberá instalar la biblioteca libedit-dev
sudo apt install libedit-devEjecute los siguientes comandos desde el directorio raíz de su repositorio clonado:
./configureConstruya JavaScript NGINX:
make La utilidad ahora debería estar disponible en
Clone el repositorio de código fuente de NGINX en un directorio fuera del repositorio de código fuente de NJS previamente clonado.
https://github.com/nginx/nginx.gitPara compilar NGINX JavaScript como un módulo dinámico, ejecute los siguientes comandos desde el directorio raíz del repositorio de código fuente de NGINX:
auto/configure --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginx Para compilar con soporte QuickJS, proporcione la ruta de inclusión y biblioteca usando las opciones --with-cc-opt= y --with-ld-opt= :
auto/configure --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginx --with-cc-opt= " -I" --with-ld-opt= " -L"
Advertencia
De forma predeterminada, este método solo construirá el módulo ngx_http_js_module . Para usar NJS con el módulo NGINX Stream, deberá habilitarlo durante el paso configure para que se compile con el binario NGINX. Al hacerlo, se compilará automáticamente el módulo ngx_stream_js_module cuando se agregue NJS a la compilación. Una forma de lograr esto es modificar el paso configure para:
auto/configure --with-stream --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginxcompilar el modulo
makeConsejo
Para compilar NGINX con JavaScript NGINX integrado en un único binario, modifique el paso configure a lo siguiente:
auto/configure --add-module= < NJS_SRC_ROOT_DIR > /nginx Si se construye como módulo(s) dinámico(s), los módulos JavaScript de NGINX estarán disponibles en el directorio
Alternativamente, puede optar por instalar los binarios NGINX y NGINX JavaScript integrados emitiendo el siguiente comando:
Importante
Si está integrado en el binario NGINX como un módulo estándar (no dinámico), este será el método de instalación más sencillo.
make install De forma predeterminada, el binario NGINX se instalará en /usr/local/nginx/sbin/nginx . Los módulos JavaScript de NGINX se copiarán en /usr/local/nginx/modules/ .
Las especificaciones técnicas de NJS son idénticas a las de NGINX.
Consulte Plataformas y sistemas operativos probados para obtener una lista completa de distribuciones compatibles.
NGINX JavaScript es compatible con todas las versiones de código abierto de NGINX a partir de nginx-1.14 y todas las versiones de NGINX Plus a partir de NGINX Plus R15.
Le animamos a colaborar con nosotros. Consulte la guía de contribución para obtener información sobre cómo hacer preguntas, informar problemas y contribuir con código.
Consulte nuestra página de lanzamiento para realizar un seguimiento de las actualizaciones.
Licencia tipo BSD de 2 cláusulas
Documentación adicional disponible en: https://nginx.org/en/docs/njs/
©2024 F5, Inc. Todos los derechos reservados. https://www.f5.com/products/nginx
