NaviServer Modules – 5.0.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 9999.
The address parameter defines the IP address to bind to. By default, this is set to 127.0.0.1 (or ::1 for IPv6), ensuring that only local connections are allowed.
The allowLoopbackEmptyUser allows to specify if a login with an empty user name 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 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.