Web Server
Use NSO's embedded web server to deliver dynamic content.
Last updated
Was this helpful?
NSO 6.1
Use NSO's embedded web server to deliver dynamic content.
Last updated
Was this helpful?
This page describes an embedded basic web server that can deliver static and Common Gateway Interface (CGI) dynamic content to a web client, commonly a browser. Due to the limitations of this web server, and/or of its configuration capabilities, a proxy server such as Nginx is recommended to address special requirements.
The web server can be configured through settings in ncs.conf . See the Manual Pages section .
Here is a brief overview of what you can configure on the web server:
toggle web server: the web server can be turned on or off.
toggle transport: enable HTTP and/or HTTPS, set IPs, ports, redirects, certificates, etc.
hostname: set the hostname of the web server and decide whether to block requests for other hostnames.
/: set the docroot from where all static content is served.
/login: set the docroot from where static content is served for URL paths starting with /login.
"/custom": set the docroot from where static content is served for URL paths starting with /custom.
/cgi: toggle CGI support and set the docroot from where dynamic content is served for URL paths starting with /cgi.
non-authenticated paths: by default, all URL paths, except those needed for the login page are hidden from non-authenticated users; authentication is done by calling the JSON-RPC login method.
allow symlinks: Allow symlinks from under the docroot.
cache: set the cache time window for static content.
log: several logs are available to configure in terms of file paths - an access log, a full HTTP traffic/trace log, and a browser/JavaScript log.
custom headers: set custom headers across all static and dynamic content, including requests to /jsonrpc.
In addition to what is configurable, the web server also GZip-compresses responses automatically if the browser handles such responses, either by compressing the response on the fly or, if requesting a static file, like /bigfile.txt, by responding with the contents of /bigfile.txt.gz, if there is such a file.
JSONRPC_SESSIONID: the JSON-RPC session id (cookie).
JSONRPC_START_TIME: the start time of the JSON-RPC session.
JSONRPC_END_TIME: the end time of the JSON-RPC session.
JSONRPC_READ: the latest JSON-RPC read transaction.
JSONRPC_READS: a comma-separated list of JSON-RPC read transactions.
JSONRPC_WRITE: the latest JSON-RPC write transaction.
JSONRPC_WRITES: a comma-separated of JSON-RPC write transactions.
MAAPI_USER: the MAAPI username.
MAAPI_GROUPS: a comma-separated list of MAAPI groups.
MAAPI_UID: the MAAPI UID.
MAAPI_GID: the MAAPI GID.
MAAPI_SRC_IP: the MAAPI source IP address.
MAAPI_SRC_PORT: the MAAPI source port.
MAAPI_USID: the MAAPI USID.
MAAPI_READ: the latest MAAPI read transaction.
MAAPI_READS: a comma-separated list of MAAPI read transactions.
MAAPI_WRITE: the latest MAAPI write transaction.
MAAPI_WRITES: a comma-separated of MAAPI write transactions.
Server or HTTP-specific information is also exported as environment variables:
SERVER_SOFTWARE:
SERVER_NAME:
GATEWAY_INTERFACE:
SERVER_PROTOCOL:
SERVER_PORT:
REQUEST_METHOD:
REQUEST_URI:
DOCUMENT_ROOT:
DOCUMENT_ROOT_MOUNT:
SCRIPT_FILENAME:
SCRIPT_TRANSLATED:
PATH_INTO:
PATH_TRANSLATED:
SCRIPT_NAME:
REMOTE_ADDR:
REMOTE_HOST:
SERVER_ADDR:
LOCAL_ADDR:
QUERY_STRING:
CONTENT_TYPE:
CONTENT_LENGTH:
HTTP_*": HTTP headers e.g. "Accept" value exported as HTTP_ACCEPT.
The tailf-tls.yang YANG module defines a structure to store TLS data in the database. It is possible to store the private key, the private key's passphrase, the public key certificate, and CA certificates.
To enable the web server to fetch TLS data from the database, ncs.conf needs to be configured.
Note that the options key-file, cert-file, and ca-cert-file, are ignored when read-from-db is set to true. See the ncs.conf.5 man page for more details.
The database is populated with TLS data by configuring the /tailf-tls:tls/private-key, /tailf-tls:tls/certificate, and, optionally, /tailf-tls/ca-certificates. It is possible to use password-protected private keys, then the passphrase leaf in the private-key container needs to be set to the password of the encrypted private key. Unencrypted private key data can be supplied in both PKCS#8 and PKCS#1 format, while encrypted private key data needs to be supplied in PKCS#1 format.
In the following example a password-protected private key, the passphrase, a public key certificate, and two CA certificates are configured with the CLI.
The SHA256 fingerprints of the public key certificate and the CA certificates can be accessed as operational data. The fingerprint is shown as a hex string. The first octet identifies what hashing algorithm is used, 04 is SHA256, and the following octets is the actual fingerprint.
When the database is populated, NSO needs to be reloaded.
After configuring NSO, populating the database, and reloading, the TLS transport is usable.
By default, only uploading 1 file per request will be processed and any remaining file parts after that will result in an error and its content will be ignored. To allow multiple files in a request you can increase /ncs-config/webui/package-upload/max-files.
The AAA infrastructure can be used to restrict access to library functions using command rules:
Note how the command is prefixed with ::webui::. This tells the AAA engine to apply the command rule to WebUI API functions. You can read more about command rules in AAA infrastructure.
The web server includes CGI functionality, disabled by default. Once you enable it in ncs.conf (see in manual Pages), you can write CGI scripts, that will be called with the following NSO environment variables prefixed with NCS_ when a user has logged in via JSON-RPC:
The web server includes support for uploading packages to /package-upload using HTTP POST from the local host to the NSO host, making them installable there. It is disabled by default but can be enabled in ncs.conf; see in Manual Pages.