AOLserver's Control Port Interface

AOLserver includes a control port interface that can be enabled with the nscp module. This control port interface allows you to telnet to a specified host and port where you can administer the server and execute database commands while the server is running.

The control port interface is a Tcl interface. Within it, you can execute Tcl commands (including AOLserver's Tcl API commands), operating system commands, SQL commands, and even edit files with the vi editor. AOLserver's Tcl commands allow you to define users, groups and permission records, as well as execute database commands.

To administer a server with the control port interface while it is running, the nscp module must be loaded into the server. To set permissions for the server, the nsperm module must also be loaded. To execute database commands while the server is running, you must also configure database services for the server, including database drivers and pools.

Configuring the Control Port Interface

An example configuration for the control port interface is shown below. Three sections of the configuration file are included. The nscp module is loaded into the /modules section for server1. The /module/nscp section defines the control port parameters, and the /module/nscp/users section defines the users who can log into the control port.

    ns_section "ns/server/server1/modules"
    ns_param nscp  nscp.so
    
    ns_section "ns/server/server1/module/nscp"
    ns_param port 9999
    ns_param address 127.0.0.1
    ns_param binary bin/nscp
    
    ns_section "ns/server/server1/module/nscp/users"
    ns_param user "nsadmin:t2GqvvaiIUbF2:"

Some things to notice about the configuration are:

• The port parameter defines the port that the interface will listen on. The default is 9999.

• The address parameter defines the hostname to bind to. The default is 127.0.0.1 so that you can only connect to the control port if you are already logged on to the computer where the server is running.

• The binary parameter defines where to find the nscp binary, which resides in the bin directory by default.

• The user parameter defines users who can log into the control port. There are three semicolon-separated fields. The first is username (nsadmin); the second is a standard unix-hashed password; the third is the path to a GNU readline 4.0 standard inputrc file. The inputrc file specifies key bindings; by default AOLserver ships with one that binds keys to the tcsh shell default settings. The inputrc file will only work properly if the nscp module is compiled with the GNU Readline library. By default, not all of the default tcsh.inputrc file is supported.

See Chapter 4 for complete information on configuration.

Using the Control Port Interface

To use the control port interface, follow these steps:

1. Telnet to the address and port number defined in the /module/nscp section for the server. For example:

       telnet localhost 9999
   

   The session responds with:

       Trying 127.0.0.1...
       Connected to localhost.
       Escape character is '^]'.
       Welcome to the AOLserver control port!
       login:
   

2. At the login prompt, type a valid username. The username must be one of the usernames defined in the /module/nscp/users section of the configuration file. For example:

       login: nsadmin
   

   The session responds with:

       password: 
   

3. At the password prompt, type the password associated with the username you specified.

   The session responds with:

       Checking authorization
       Login successful!
       214 commands
       sourcing /modules/nscp/tcsh.inputrc
       server1> 
   

   Note that the inputrc file is sourced when the session starts.

4. At the server1 prompt, you may type any of the following types of commands:
   • Tcl commands: See the AOLserver Tcl Developer's Guide for detailed information on the available Tcl commands. For example, you can type the ns_info command to find out various information about the server:

       	server1> ns_info pageroot
       	/disk5/ohenry/servers/server1/pages
   

   • Operating system commands: Operating system commands must be preceded by an exclamation point (!). For example:

       	server1> !who
       	ohenry   ttyq1        Apr 27 07:57
       	ohenry   ttyq2        Apr 27 08:41
       	ohenry   ttyq3        Apr 27 15:01
   
   or:
   
   
       	server1> !csh
       	%
   

   • vi Editor: You can type vi at the prompt to invoke the vi editor. Inside the editor, you can type whatever commands you like. When you save and exit, the commands will be executed.

   • exit: Type exit at the prompt to close the connection to the control port.

       	server1> exit
   

5. You can enter SQL commands by entering DB mode. Enter DB mode by executing the ns_cport db command and specifying a database pool. SQL commands can span multiple lines and must be terminated by a semicolon. To return to Tcl mode to enter Tcl commands, enter a semicolon by itself. For example:

       	server1> ns_cport db devpool
       	DB mode started.
       	Enter SQL statements terminated with a semicolon.
       	To return to Tcl mode, type a semicolon on a line by itself.
       	server1> select * from names;
       	first      last    age
       	------------------------
       	Al         Smith   23
       	Hugh       James   30
       	server1> insert into names
       	=>(first, last, age)
       	=>values
       	=>('Anita', 'Bass', 38)
       	=>;
       	server1> ;
       	DB mode exited; now processing Tcl commands.
       	server1> 
   

   If you type ns_cport db with no pool name, a list of pools is displayed. For example:

       	server1> ns_cport db
       	Please specify one of the following db pools:
       	devpool: Development database
       	salespool: Sales database
       	server1> ns_cport db devpool
   

6. You can get help in the control port by typing a question mark, '?' in the following ways:
   • If you type a question mark by itself, some brief help is provided as shown below:

       server1> ?
       ?                  Show this help text
       ?[string]          Do an apropos search on [string] of AOLserver
                          commands
       ![command]         Execute [command]; for example, !/bin/sh 
                                         runs a shell
       vi                 Run vi and then execute the buffer, if saved
       exit               Exit the control port
       [tclcommand]       Execute [tclcommand] within AOLserver
       ns_menu            An easy-to-use menu with basic administration
                          commands
       ns_cport db [pool] Evaluate SQL statements directly commands
       
   

   • If you type a question mark followed by a string, a search for the string is performed of the Tcl man pages, and matching commands are displayed. For example:

       server1> ?write
       ns_rwlock             - Create, destroy, and manipulate       
                                                   read/write locks
       ns_write              - Write raw content back to the client
       ns_writecontent       - Write content to a file
       ns_writefp            - Write file contents to the connection
       
   

7. Some other features of the control port interface are:
   • Repeat commands: There is a history mechanism; you can use the up-arrow and down-arrow keys, or the ^P and ^N keystrokes to scroll through previous commands.

   • Tab completion: If you type part of a command (such as ns_logr) and then press the tab key, the rest of the command (ns_logroll) will be filled in for you. If there are multiple possibilites for the end of the command, press the tab key twice to get a list of them.

Administering AOLserver in the Control Port

An interactive interface for administering AOLserver is available when you execute the ns_menu command in the control port interface.

Top Level Menu

When you type ns_menu in the control port interface, the following menu is displayed:

    server1> ns_menu
    1. Logging
    2. Thread info
    3. Caching
    4. Change password
    5. Restart server
    Your choice [1-5]: 

Type a menu number between 1 and 5 at the prompt. Each choice corresponds to a sub-menu. The sub-menus are described below.

Logging Option

If you type 1 at the top level menu, the logging menu is displayed:

    1. Tail
    2. Adjust
    Your choice [1-2]:

The logging menu allows you to view the server log and adjust the logging level of the available logging realms. The menu options are described below:

• Tail: Choosing this option performs a "tail -f" of the server log in the background so that you can see it while using the control port.

• Adjust: Choosing this option shows you a menu of available logging realms (see the ns_modlogcontrol Tcl function). You can select one of the logging realms and adjust the logging level to increase or decrease the amount of logging information you get. For example:

      Available realms:
      nsd.pidfile
      nsd.dns
      nsd.adp
      nsd.sched
      nslog
      nsd.return
      nsd.socket
      nsperm
      nsd.tcl
      nsd.fastpath
      nsd.cache
      nsd.db
      nsd.mime
      nscp
      nsd
      nsd.geturl
      Your choice: nsd
      The current logging level for realm nsd is 'notice'
      Possible logging levels are:
      fatal bug error warning notice debug
      Enter new level: debug
      Done.
  

Thread Info Option

If you type 2 at the top level menu, information about the state of the server is displayed. For example:

    Min threads:      2
    Max threads:      20
    Current threads:  2
    Idle threads:     2
    Stopping threads: 0

Caching Option

If you type 3 at the top level menu, the caching menu is displayed:

    1. View stats
    Your choice [1-1]: 

The menu option is described below:

• View stats: Choosing this option shows the currently-registered caches and displays statistics about the one you select. For example:

      Currently registered caches are:
      adp
      fastpath
      Your choice: fastpath
      Max size: 5120000  Current size: 34213
      entries: 32  flushed: 0  hits: 20  misses: 20  hitrate: 50
  

Change Password Option

If you type 4 at the top level menu, you can change a user's nsperm password. (Note that a user's nsperm password is not necessarily the same as the user's control port password.) For example:

    This will change a user's password in the nsperm module.
    Enter user name: nsadmin
    Enter user's old password or the nsadmin password: 
    Enter new password: 
    Re-enter new password:

Passwords are not echoed to the screen. To change the password of a user other than yourself, enter the nsadmin password when prompted for the user's old password.

Restart Server Option

If you type 5 at the top level menu, the server is restarted. This option only works if the nsd binary exists in the directory [ns_info home]/bin/nsd.