NGINX JavaScript, également connu sous le nom de NJS, est un module dynamique pour NGINX qui permet l'extension des fonctionnalités intégrées à l'aide de la syntaxe JavaScript familière. Le langage NJS est un sous-ensemble de JavaScript, compatible avec ES5 (ECMAScript 5.1 Strict Variant) avec certaines extensions ES6 (ECMAScript 6) et plus récentes. Voir compatibilité pour plus de détails.
NGINX JavaScript est fourni sous forme de deux modules dynamiques pour NGINX (ngx_http_js_module et ngx_stream_js_module) et peut être ajouté à toute installation NGINX Open Source ou NGINX Plus prise en charge sans recompilation.
Le module NJS permet aux administrateurs NGINX de :
Voir des exemples et nos différents projets développés avec NJS :
Étend la fonctionnalité NGINX Plus pour communiquer directement avec les fournisseurs d'identité compatibles OIDC, authentifiant les utilisateurs et autorisant le contenu fourni par NGINX Plus.
Implémentation de référence de NGINX Plus en tant que fournisseur de services pour l'authentification SAML.
Expose le point de terminaison des métriques Prometheus directement à partir de NGINX Plus.
Conseil
NJS peut également être utilisé avec le serveur d'applications NGINX Unit. Apprenez-en davantage sur l'API de contrôle de NGINX Unit et sur la façon de définir des appels de fonction avec NJS.
Suivez ces étapes pour télécharger et installer les binaires Linux JavaScript NGINX et NGINX précompilés. Vous pouvez également choisir de construire le module localement à partir du code source.
Suivez ce guide pour ajouter le référentiel officiel de packages NGINX à votre système et installer NGINX Open Source. Si NGINX Open Source ou NGINX Plus est déjà installé, ignorez la partie d'installation de NGINX dans la dernière étape.
Une fois le référentiel provisionné, vous pouvez installer NJS en exécutant la commande suivante :
sudo apt install nginx-module-njssudo yum install nginx-module-njssudo apk add nginx-module-njs@nginxsudo zypper install nginx-module-njsConseil
Le référentiel de packages comprend un module alternatif qui active les symboles de débogage. Bien qu'il ne soit pas recommandé pour les environnements de production, ce module peut être utile lors du développement de configurations basées sur NJS. Pour télécharger et installer la version de débogage du module, remplacez le nom du module dans la commande précédente par nginx-module-njs-dbg .
Les scripts d'installation du package installent deux modules, prenant en charge les contextes NGINX http et stream .
ngx_http_js_module
Ce module NJS permet la manipulation des données transmises via HTTP.
ngx_stream_js_module
Ce module NJS permet la manipulation des données transmises via des protocoles de flux tels que TCP et UDP.
Par défaut, les deux modules sont installés dans le répertoire /etc/nginx/modules .
L'utilisation de NJS implique l'activation du module, l'ajout de fichiers JavaScript avec des fonctions définies et l'appel de fonctions exportées dans les fichiers de configuration NGINX.
NGINX JavaScript est un module pour NGINX Open Source ou NGINX Plus. Si vous ne l'avez pas déjà fait, suivez ces étapes pour installer NGINX Open Source ou NGINX Plus. Une fois installée, assurez-vous que l'instance NGINX est en cours d'exécution et capable de répondre aux requêtes HTTP.
Exécutez la commande suivante pour démarrer NGINX :
sudo nginxcurl -I 127.0.0.1Vous devriez voir la réponse suivante :
HTTP/1.1 200 OK
Server: nginx/1.25.5 Une fois installés, l'un (ou les deux) module(s) NJS doivent être inclus dans le fichier de configuration NGINX. Sur la plupart des systèmes, le fichier de configuration NGINX se trouve par défaut dans /etc/nginx/nginx.conf .
sudo vi /etc/nginx/nginx.confUtilisez la directive load_module dans le contexte de niveau supérieur (« principal ») pour activer l'un (ou les deux) module(s).
load_module modules/ngx_http_js_module.so;
load_module modules/ngx_stream_js_module.so; Les fichiers de script NJS sont généralement nommés avec une extension .js et placés dans le répertoire /etc/nginx/njs/ . Ils sont généralement constitués de fonctions qui sont ensuite exportées, les rendant disponibles dans les fichiers de configuration NGINX.
NJS fournit une collection d'objets avec des méthodes et propriétés associées qui ne font pas partie des définitions ECMAScript. Consultez la référence complète de ces objets et comment ils peuvent être utilisés pour étendre et personnaliser davantage NGINX.
Voici un exemple de base de « Hello World ».
La fonction hello de ce fichier renvoie un code de réponse d'état HTTP 200 OK accompagné de la chaîne « Hello World ! », suivi d'un saut de ligne. La fonction est ensuite exportée pour être utilisée dans un fichier de configuration NGINX.
Ajoutez ce fichier au répertoire /etc/nginx/njs :
function hello ( r ) {
r . return ( 200 , "Hello world!n" ) ;
}
export default { hello } Nous modifions notre configuration NGINX ( /etc/nginx/nginx.conf ) pour importer le fichier JavaScript et exécuter la fonction dans des circonstances spécifiques.
# 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;
}
}
}Pour une liste complète des directives njs, consultez les pages de documentation des modules ngx_http_js_module et ngx_stream_js_module.
Conseil
Une version plus détaillée de cet exemple et d'autres exemples peuvent être trouvés dans le référentiel officiel njs-examples.
NGINX JavaScript s'installe avec un utilitaire d'interface de ligne de commande. L'interface peut être ouverte comme un shell interactif ou utilisée pour traiter la syntaxe JavaScript à partir de fichiers prédéfinis ou d'une entrée standard. Étant donné que l'utilitaire s'exécute indépendamment, les objets spécifiques à NGINX tels que HTTP et Stream ne sont pas disponibles dans son environnement d'exécution.
$ 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
8Les étapes suivantes peuvent être utilisées pour créer NGINX JavaScript en tant que module dynamique à intégrer dans NGINX ou en tant que binaire autonome à utiliser comme utilitaire d'interface de ligne de commande.
Important
Pour créer le module à utiliser avec NGINX, vous devrez également cloner, configurer et créer NGINX en suivant les étapes décrites dans ce document.
La plupart des distributions Linux nécessiteront l'installation de plusieurs dépendances afin de créer NGINX et NGINX JavaScript. Les instructions suivantes sont spécifiques au gestionnaire de paquets apt , largement disponible sur la plupart des distributions Ubuntu/Debian et leurs dérivés.
sudo apt install gcc makesudo apt install libpcre3-dev zlib1g-dev libssl-dev libxml2-dev libxslt-devPour construire avec QuickJS, vous devrez également créer la bibliothèque QuickJS :
git clone https://github.com/bellard/quickjs
cd quickjs
CFLAGS= ' -fPIC ' make libquickjs.aAvertissement
Il s'agit de l'ensemble minimal de bibliothèques de dépendances nécessaires pour créer NGINX et NJS. D'autres dépendances peuvent être nécessaires si vous choisissez de créer NGINX avec des modules supplémentaires. Surveillez le résultat de la commande configure abordée dans les sections suivantes pour obtenir des informations sur les modules pouvant être manquants.
À l'aide de votre méthode préférée, clonez le référentiel JavaScript NGINX dans votre répertoire de développement. Voir Clonage d'un référentiel GitHub pour une aide supplémentaire.
https://github.com/nginx/njs.gitLes étapes suivantes sont facultatives et nécessaires uniquement si vous choisissez de créer NJS en tant qu'utilitaire autonome.
Pour utiliser le shell interactif NJS, vous devrez installer la bibliothèque libedit-dev
sudo apt install libedit-devExécutez les commandes suivantes à partir du répertoire racine de votre dépôt cloné :
./configureCréez du JavaScript NGINX :
make L'utilitaire devrait maintenant être disponible dans
Clonez le référentiel de code source NGINX dans un répertoire en dehors du référentiel source NJS précédemment cloné.
https://github.com/nginx/nginx.gitPour créer NGINX JavaScript en tant que module dynamique, exécutez les commandes suivantes à partir du répertoire racine du référentiel de code source NGINX :
auto/configure --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginx Pour créer avec la prise en charge de QuickJS, fournissez l'inclusion et le chemin de la bibliothèque à l'aide des options --with-cc-opt= et --with-ld-opt= :
auto/configure --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginx --with-cc-opt= " -I" --with-ld-opt= " -L"
Avertissement
Par défaut, cette méthode construira uniquement le module ngx_http_js_module . Pour utiliser NJS avec le module NGINX Stream, vous devrez l'activer lors de l'étape configure afin qu'il soit construit avec le binaire NGINX. Cela compilera automatiquement le module ngx_stream_js_module lorsque NJS sera ajouté à la build. Une façon d'y parvenir consiste à modifier l'étape configure pour :
auto/configure --with-stream --add-dynamic-module= < NJS_SRC_ROOT_DIR > /nginxCompiler le module
makeConseil
Pour créer NGINX avec JavaScript NGINX intégré dans un seul binaire, modifiez l'étape configure comme suit :
auto/configure --add-module= < NJS_SRC_ROOT_DIR > /nginx S'ils sont construits en tant que module(s) dynamique(s), le(s) module(s) JavaScript NGINX seront disponibles dans le répertoire
Vous pouvez également choisir d'installer les binaires JavaScript NGINX et NGINX intégrés en exécutant la commande suivante :
Important
S'il est intégré au binaire NGINX en tant que module standard (non dynamique), ce sera la méthode d'installation la plus simple.
make install Par défaut, le binaire NGINX sera installé dans /usr/local/nginx/sbin/nginx . Le(s) module(s) JavaScript NGINX seront copiés dans /usr/local/nginx/modules/ .
Les spécifications techniques de NJS sont identiques à celles de NGINX.
Voir Systèmes d'exploitation et plates-formes testés pour une liste complète des distributions prises en charge.
NGINX JavaScript est pris en charge par toutes les versions NGINX Open Source à partir de nginx-1.14 et toutes les versions de NGINX Plus à partir de NGINX Plus R15.
Nous vous encourageons à vous engager avec nous. Veuillez consulter le guide de contribution pour savoir comment poser des questions, signaler des problèmes et contribuer au code.
Consultez notre page de publication pour suivre les mises à jour.
Licence de type BSD à 2 clauses
Documentation supplémentaire disponible sur : https://nginx.org/en/docs/njs/
©2024 F5, Inc. Tous droits réservés. https://www.f5.com/products/nginx
