NaviServer Modules – 5.2.0a
nscp - NaviServer Control Port Guide
This document describes the NaviServer control port interface provided by the nscp module. The control port offers a Tcl-based administration interface that allows you to connect to a designated host and port, and to perform server management and database operations while the server is running.
NaviServer provides a control port interface that can be enabled by loading the nscp module. This interface lets you connect to a specified host and port using a telnet client to administer the server and execute database commands on the running system.
The control port offers direct access to the Tcl API of the running server. Once logged in, you can execute nearly any Tcl command available in the Tcl libraries with the exception of commands that require a dedicated connection thread (for example, all subcommands of ns_conn except ns_conn isconnected).
To effectively manage the server through the control port, ensure that:
The nscp module is loaded and configured (see details below).
Optionally, the nsperm module may be used to provide authentication. In this case, make sure it is loaded and configured for your needs.
To use the control port, a user must connect via telnet to the configured port and log in with a username and password. Authentication is handled as follows:
If the username entered at the login prompt is empty, and the connection originates from a loopback address, and the configuration variable permitting unauthenticated access is enabled, the login is accepted without further authentication.
If a username is provided, the system first attempts to authenticate using the nsperm module (if it is loaded).
If the nsperm module is not available, authentication falls back to using the configured control port users.
Below is an example configuration that demonstrates how to enable and configure the control port. This example shows three configuration sections:
The nscp module is loaded in the /modules section for $server.
The /module/nscp section defines the control port parameters.
The /module/nscp/users section defines optionally the configured control port users.
#
# Control port -- nscp
#
ns_section ns/server/$server/module/nscp {
ns_param port 9999 ;# Control port listens on port 9999
ns_param address 127.0.0.1 ;# For security, use 127.0.0.1 only
#ns_param allowLoopbackEmptyUser on ;# default: off
ns_param echopasswd off
ns_param cpcmdlogging off
}
# Optional configuration of control port users
ns_section ns/server/$server/module/nscp/users {
#
# The default password for nsadmin is "x". You should change it.
# For example, type "ns_crypt /newpassword/ /salt/" and put the encrypted string
# below.
ns_param user "nsadmin:t2GqvvaiIUbF2:" ;# sample user="nsadmin", pw="x".
}
ns_section ns/server/$server/modules {
# ...
ns_param nscp nscp.so
}
Important points regarding this configuration:
The port parameter defines the port that the interface will listen on. The default is 2080. Port 0 selects one ephemeral port shared by all successfully bound addresses.
The address parameter accepts a nonempty Tcl list of IP addresses and hostnames. A single address remains valid with unchanged authentication behavior. Each hostname is expanded to all addresses returned by the system resolver, without outbound AI_ADDRCONFIG filtering (which can exclude loopback-only IPv6 in containers). localhost therefore enables IPv4 and IPv6 loopback listeners when both are available. Equivalent numeric addresses and overlaps between list entries are deduplicated. At most 64 distinct resolved addresses are supported. The default remains the build's loopback address (::1 with IPv6 support, otherwise 127.0.0.1). No wildcard fallback is introduced. All listeners share the configured port, users, echo and authentication settings. ns_info sockcallbacks reports each numeric endpoint. Resolution/list errors prevent listener creation. Individual bind or callback-registration failures are logged; other addresses are still attempted. At least one listener must succeed. Thus a host with only one usable address family can still use localhost. Review startup notices to see the effective listeners. Keep the administrative console restricted to trusted interfaces. Explicit wildcard addresses can expose it externally; localhost follows the system resolver configuration.
ns_param address 127.0.0.1 ;# existing IPv4-only configuration
ns_param address localhost ;# available resolved loopback addresses
ns_param address {127.0.0.1 ::1} ;# explicit IPv4 and IPv6 listeners
The allowLoopbackEmptyUser allows one to specify if a login with an empty username should be allowed from a loopback address (i.e., a user logged in on the same host).
The echopasswd parameter controls whether the password is echoed as it is typed; its default setting is off.
The cpcmdlogging parameter determines whether entered commands are logged in the system log; its default is off.
The user parameter in the users section defines users who can log into the control port. There are three semicolon-separated fields. The first is username (nsadmin); the second is a Unix-like password hash. You can create a password by typing "ns_crypt /mypasswd/ /salt/". As with Unix, only the first four characters are used.
See the Configuration Reference for complete information on configuration.
The nscp module defines a single command:
Returns the list of usernames permitted to connect via the control port.
To use the control port interface, follow these steps:
Connect via Telnet: Telnet to the IP address and port specified in the /module/nscp section. For example:
telnet 127.0.0.1 9999
Upon connecting, the session will display:
Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. login:
Login: At the login prompt, enter a valid username as defined in the /module/nscp/users section. For example:
login: nsadmin
The session will then prompt for a password:
password:
Enter Password: Type the password associated with the username (the default is "x"). We assume here, that the nsperm module is not loaded. If the credentials are correct, the session will display a welcome message similar to:
Welcome to SERVER running at /usr/local/ns/bin/nsd (pid NNNNNN) NaviServer/MAJOR.MINOR:PATCHLEVEL for linux built on MON/DAY/YEAR at HH:MM:SS SERVER:nscp 1>
Execute Commands: At the control port prompt, you can execute nearly any Tcl command available in NaviServer's Tcl libraries and ADP pages.
Exit: To log off from the control port, simply type exit.
When connected via the control port, you might the find the following plain Tcl commands to be useful:
lsort [info commands]
This command returns a complete list of available commands. You can also execute nearly any Tcl command, including core Tcl commands and any ns_* commands. To see a sorted list of NaviServer Tcl commands, type:
lsort [info commands ns*]
Some useful NaviServer commands for nscp are:
ns_shutdown - Shuts down the server.
ns_info uptime - Displays how long the server has been running.
ns_info threads - Lists the current number of running threads.
exit - Exits the control port session.
The following parameters are accepted in the ns/server/$server/module/nscp section.
Local address on which the control port listens; should normally be restricted to a trusted interface such as loopback (e.g. 127.0.0.1)
Type: address
TCP port on which the control port listens
Type: integer