Administration Functions

$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/api/admin.html,v 1.2 2004/07/20 23:44:26 dossy Exp $


Note! Updated Tcl API documentation in progress is now available on the wiki.


ns_config

Extract information from the configuration file.

Syntax

ns_config ?-exact | -bool | -int? section key ?default?

Description

The ns_config function returns the value associated with the key in the specified section of the configuration file. If the default argument is specified, and the specified section and key aren't found in the configuration file, the specified default is returned. If the default argument is not specified in this situation, "" is returned.

If -exact is specified, matching on key is case-sensitive. By default matching is case-insensitive.

If -bool is specified, ns_config will perform the conversion of a boolean value from "on", "1", "y", "yes", "t", and "true" to "1", and it will convert a boolean value of "off", "0", "n", "no", "f", and "false" to "0". If a boolean contains any other value, a warning is written to the log file and an empty string {"") is returned. If no value is specified in the configuration file for the specified key, an empty string ("") is returned.

If -int is specified, ns_config will return the integer value of the specified key. If there is a non-integer value in the configuration file, a warning is written to the log file and an empty string ("") is returned.

Example

set path ns/server/myserver set xyz [ns_config -bool $path Verbose 1]



ns_configsection

Return values of a configuration file section

Syntax

ns_configsection section

Description

This function returns an ns_set of all the parameter values for the specified configuration file section. The ns_set contains key/value pairs for each parameter.

Example

ns_configsection "ns/server/server1/tcl"



ns_configsections

Return values of all configuration file sections

Syntax

ns_configsections

Description

This function returns a tcl list of ns_sets of all the parameter values for all of the configuration file sections. There is one item in the list for each configuration file section, and the corresponding ns_set contains key/value pairs for each parameter in the section.



ns_eval

Evaluate Tcl.

Syntax

ns_eval arg ?arg? ?arg?

Description

ns_eval evaluates the Tcl passed in to this function. The Tcl is evaluated in all the Tcl interpreters for this virtual server. You can use this command to maintain global variables. For example, if you execute:
ns_eval set g 1

in one interpreter, later operations will see $g equal to 1 no matter what interpreter they are assigned to.



ns_info

Find information about AOLserver

Syntax

ns_info boottime

ns_info config

ns_info home

ns_info host

ns_info hostname

ns_info interp

ns_info label

ns_info location

ns_info log

ns_info name

ns_info pageroot

ns_info platform

ns_info port

ns_info server

ns_info tcllib

ns_info uptime

ns_info version

Description

ns_info boottime returns the system time in seconds when the server booted up.

ns_info config returns the file name of the configuration file.

ns_info home returns the directory where the AOLserver was installed.

ns_info host is no longer available. Use ns_conn location.

ns_info hostname returns the name of the host that the server is running on (e.g., www.myhost.com).

ns_info interp returns the number of the Tcl interpreter currently being used.

ns_info label returns the source code label for the server. If no label was used, "unlabeled" is returned. You can use this function to provide the source code label when you report problems with the server. Also, the /NS/About page for the server reports the source code label along with the other server information.

ns_info location is obsolete. Use ns_conn location instead.

ns_info log returns the location of the server log file (e.g., /home/myserver/log/server.log).

ns_info name returns the name of the AOLserver. It's usually "AOLserver."

ns_info pageroot returns the directory containing the HTML pages for this virtual server.

ns_info platform returns the name of the platform that the server is running on (e.g., Solaris).

ns_info port is no longer available. Use ns_conn location.

ns_info server returns the name of this virtual server.

ns_info tcllib returns the directory where the AOLserver Tcl source code resides for this virtual server.

ns_info uptime returns the time in seconds that the server has been up.

ns_info version returns the version of the AOLserver.



ns_kill

Send a signal to a process

Syntax

ns_kill ?-nocomplain? pid signal

Description

This function spends the specified signal to the specified process ID (pid). If -nocomplain is specified, no error will be returned on failure.



ns_library

Return directory for a server's Tcl library

Syntax

ns_library

Description

ns_library returns the directory where the server-specific Tcl source code resides. This directory location can be specified with the Library configuration parameter.



ns_log

Write messages to the error log

Syntax

ns_log severity message

Description

While the AOLserver is running it logs various events from Notices to Fatal errors. Usually the AOLserver is running in the background, in which case these messages are placed in the server log. In absence of an ServerLog key in the AOLserver nsd.ini file, this file is the /log/error.log under the AOLserver installation directory. When the AOLserver is running in the foreground the messages are redirected to stderr.

ns_log writes the message to the server error log file. Allowable values for severity are:

Notice

Something interesting occurred.

Warning

Something that could mean something bad occurred.

Error

Something bad occurred.

Fatal

Something extremely bad occurred. The server will shut down after logging the message.

Bug

Something occurred that implies that there is a bug in the code.

Debug

If the server is in Debug mode, the message is printed. Debug mode is specified in the [ns/parameters] section of the configuration file. Otherwise, the message is not printed.

Example

This is an excerpt from an AOLserver error.log: [12/Jul/1995:18:10:13 -0700][1103] Notice: starting servers.

See Also

Ns_Log(), Ns_LogRaw() (C API)

nsd.ini (AOLserver Configuration File)



ns_logroll

Roll server log

Syntax

ns_logroll

Description

This function forces a roll of the server log.



ns_modulepath

Return server directory path

Syntax

ns_modulepath server

Description

This function returns the path of the specified server's directory. The result will be of the form: path_beginning/servers/server.



ns_param

Define a parameter in the configuration file

Syntax

ns_param key value

Description

This function can only be used in the configuration file. It defines a parameter by specifying its name (key) and its value.

Example

ns_param Port 8000



ns_passwordcheck

Verify a user/password combination

Syntax

ns_passwordcheck ?-server servername? user password

Description

This function returns 1 (one) if the user and password combination is legitimate. It returns 0 (zero) if either the user does not exist or the password is incorrect. If no servername is specified, the current virtual server is used.



ns_perm

Add users, groups, and permissions

Syntax

ns_perm adduser name encpass userfield ?-allow | -deny host ...?

ns_perm addgroup name user ?user ...?

ns_perm allowuser ?-noinherit? method url user

ns_perm denyuser ?-noinherit? method url user

ns_perm allowgroup ?-noinherit? method url group

ns_perm denygroup ?-noinherit? method url group

ns_perm checkpass user passwd

ns_perm setpass user encpass

Description

Note: To use this function after server startup, the SkipLocks parameter (see page 69 in the AOLserver Administrator's Guide) must be set to On.

ns_perm adduser adds the user with the specified name and the encrypted password (encpass) and the specified user text (userfield) into the users database.

If -allow and hostnames are specified, the user will be allowed on the specified hostnames. If -deny and hostnames are specified, the user will be denied on the specified hostnames. The hostname must be specified as ipaddress/netmask or dnshostname. For example: 128.2.142.0/255.255.255.0 or www.microsoft.com or .microsoft.com.

ns_perm addgroup creates a new group with the specified name that includes the users listed after the name.

ns_perm allowuser allows the specified user access to the specified method and URL combination. If -noinherit is specified, only access to the exact URL is allowed; otherwise, URLs under that URL are allowed as well.

ns_perm denyuser denies the specified user access to the specified method and URL combination. If -noinherit is specified, only access to the exact URL is denied; otherwise, URLs under that URL are denied as well.

ns_perm allowgroup allows the specified group access to the specified method and URL combination. If -noinherit is specified, only access to the exact URL is allowed; otherwise, URLs under that URL are allowed as well.

ns_perm denygroup denies the specified group access to the specified method and URL combination. If -noinherit is specified, only access to the exact URL is denied; otherwise, URLs under that URL are denied as well.

ns_perm checkpass checks that the specified plain-text password is correct for the specified user. A Tcl error is thrown if it does not match.

ns_perm setpass updates the specified user's password to the encrypted password encpass. The password should be encrypted using ns_encrypt.



ns_permpasswd

Update existing password

Syntax

ns_permpasswd user oldpass newpass

Description

ns_permpasswd updates an existing user's password, both in the running server's memory as well as in the passwd file on disk. The user is the name of the user whose password is to be updated. The oldpass argument is the user's old password, or the nsadmin password, in plain text. The newpass argument is the new password in plain text.



ns_section

Define a section in the configuration file

Syntax

ns_section section

Description

This function can only be used in the configuration file. It defines a section in the configuration file. It is followed by a series of ns_param function calls to define the parameters in the section.

Example

ns_section "ns/server/server1/adp"



ns_server

Get information about the virtual server

Syntax

ns_server ?-server servername? active

ns_server ?-server servername? all

ns_server ?-server servername? connections

ns_server ?-server servername? queued

ns_server ?-server servername? threads

ns_server ?-server servername? verbose ?on/off?

ns_server ?-server servername? waiting

Description

ns_server active returns a list of lists containing information about the currently-active connections for the specified virtual server, or the current virtual server if none is specified. For each active connection, the following information is returned:

id:

An ever-increasing number that identifies the connection.

peer:

The remote address.

state:

The state of the connection, one of the following:

queued: waiting for a thread

init: thread is initializing a connection

request: reading the request

authorize: authorizing the request

running: running the request

tcl: in a Tcl script

traces: running all trace procedures

method:

The request method. If the state is before request, an asterisk "*" is shown.

url:

The request URL. If the state is before request, an asterisk "*" is shown.

time:

The number of seconds since the connection started.

bytes:

The number of bytes sent through the connection.

For example:

id

peer

state

method

url

time

bytes

3

128.111.100.50

traces

GET

/some/page.htm

5

1134

ns_server all returns the same information as ns_server active about both active and waiting connections for the specified virtual server, or the current virtual server if none is specified.

ns_server connections returns the total number of connections for the specified virtual server, or the current virtual server if none is specified.

ns_server queued returns the same information as ns_server active about the waiting connections for the specified virtual server, or the current virtual server if none is specified.

ns_server threads returns a Tcl list containing the minimum number of threads, the maximum number of threads, the number of currently active threads, the number of idle threads, and the number of stopping threads for the specified virtual server, or the current virtual server if none is specified. For example: {min 0} {max 50} {current 2} {idle 1} {stopping 0}

ns_server verbose returns 1 if the server is in verbose mode and 0 if it is not for the specified virtual server, or the current virtual server if none is specified. If "on" is specified, sets verbose mode on. If "off" is specified, sets verbose mode off.

ns_server waiting returns the number of waiting connections for the specified virtual server, or the current virtual server if none is specified.



ns_set_precision

Set precision for floating-point to string conversions

Syntax

ns_set_precision precision

Description

The precision argument is a decimal number specifying the number of significant digits to include when converting floating-point numbers to strings. The default number of significant digits used is 6 digits. You can set precision to 17 for conversions with IEEE floating-point numbers to allow double-precision values to be converted to strings and back to binary with no loss of precision.

Notes

This function replaces the tcl_precision variable, which is not recognized by expr.



ns_shutdown

Shut down the server

Syntax

ns_shutdown ?nseconds?

Description

ns_shutdown shuts down the server. The nseconds argument specifies a time limit in which the server is to shut down. If the server hasn't stopped within the time limit, it is immediately stopped, aborting any active connections. The default value of nseconds is 0.