nph(1)

NAME
nph - new PH client

SYNOPSIS
nph [options] [selectors [return field1 ...] [@domain]]
nph [options]

VERSION
This man page documents version 1.2 of nph.

DESCRIPTION
nph is a new PH client. It uses the libphclient API and contains a number of new features and usability improvements over the old PH client.

STARTUP
If nph is invoked with non-option arguments, they are interpreted as a query command. nph will perform the query and exit immediately. Otherwise, nph will start up in interactive mode and accept commands from stdin. To determine what PH server to connect to, nph looks in three places. If the -s commandline option (described below) is given, the specified server is used. Otherwise, if the PH_SERVER environment variable is set, its value is used. Finally, if neither of the previous sources specify a server, the file /usr/local/etc/ph_server is read if it exists. If no server is found, nph will not start. Once a server is selected, nph then searches for a startup file containing a list of commands to be automatically executed. If the -f commandline option (described below) is given, it specifies the name of the startup file to use. Otherwise, it looks for the file ${HOME}/.nphrc.server, where server is the name of the selected server. If that file does not exist, it looks for ${HOME}/.nphrc. Lastly, if neither of the previous files exist, it reads /usr/local/etc/nphrc.

COMMANDLINE OPTIONS

-c  Enable "confirmedits" option (see below).

-C  Do not read the system-wide nphrc or the user's ${HOME}/.nphrc file.

-d  Enable "debug" option (see below).

-f rcfile
    Tells nph to use rcfile as the startup file.

-F field1 field2 ...
    Set the "returnfields" option to "field1 field2 ..." (see below).

-m  Disable the "usepager" option (see below).

-r  Disable the "canonicaladdrs" option (see below).

-R  Use a reserved port on the local end of the connection. (This will only succeed if nph is running as root.)

-s server[:port]
    Specify which PH server (and optionally, what port) to connect to. If the port is not given, the port corresponding to the csnet-ns service is used (usually port 105).

INTERACTIVE MODE
The following commands are supported in interactive mode:

id text
    Identify yourself for the PH server's logs. Users do not normally need to use this command.

external
    Mark the session as external, or non-local. This prevents the user from accessing fields marked with the LocalPub attribute.

suser alias
    Assume the privileges of alias. Only heros may execute this command.

login alias
    Log in to the server as user alias. The login command uses the authentication mechanism indicated by the authtype option.

logout
    Log out of the PH server.

passwd
    Change the password of the currently logged-in user.

password
    Synonym for passwd.

option [option=value]
    With no arguments, displays the current value of all client-side options. If arguments are given, the option command sets the given option to the given value. See below for more information on options.

switch
    Synonym for option.

source file
    Read and executes commands from file.

.   Synonym for source.

<   Synonym for source.

help [command]
    Displays a one-line help message for command. If no arguments are given, the help command displays information for all valid commands.

?   Synonym for help.

quit
    Disconnect from the PH server and exit nph.

bye Synonym for quit.

exit
    Synonym for quit.

stop
    Synonym for quit.

whoami
    Displays the currently logged-in username, plus the name of the server.

status
    Prints the PH server's status information.

motd
    Synonym for status.

set [option[=value]]
    Without arguments, displays the current value of all server-side options. With arguments, it sets the value of the given option. If the value is not specified, the default value is "on".

siteinfo
    Displays the site-specific configuration list from the PH server.

connect host[:port]
    Connects to the specified server and disconnects from the currently-connected server.

serveradd server [site]
    Adds a server and corresponding site name to the list of known PH servers.

listservers [domain]
    Displays the list of known PH servers. If domain is listed, only servers in that domain will be displayed. domain must be composed of at least two '.'-delimited portions of the server name to search for (e.g., "uiuc.edu" instead of "edu").

fields [field]
    Displays information about the fields supported by the server. Without arguments, it displays all supported fields. With arguments, it displays only the listed fields.

edit field [alias]
    Edit the named field using the external editor specified by the editor client option. The user must be logged in before using this command. If alias is given, edit the field from the entry for alias; otherwise, edit the field from the logged-in user's entry. To edit a field from some entry other than that of the logged-in user, the logged-in user must either have hero privileges or must be allowed to edit the specified entry by proxy.

query selectors... [return fields...] [@domain]
    Retrieve entries from the PH server. The selectors specify the entries to retrieve (as described in SELECTING ENTRIES below). The optional return clause specifies which fields of the matching entries should be returned. If no return clause is given and the returnfields option is unset, only fields marked with the Default attribute will be returned by the server. If the @domain argument is given, nph will attempt to find the PH server for the specified domain. If found, the query will be sent to that server, rather than the current server. Once the query is complete, the connection to the original server will be resumed without interruption.

change selectors... make|force assignments...
    Change entries on the server. The user must be logged in before using this command and must have permission to change the selected entry or entries. The selectors specify the entries to which the changes should be applied. The assignments specify the changes to apply to all matching entries. The force keyword allows the user to make a non-encrypted change to fields marked with the Encrypt keyword. Otherwise, all changes will normally use the make keyword instead.

make assignments...
    This is a short form of the change command which operates on the entry of the logged-in user.

delete selectors...
    Delete entries. The user must be logged in and have hero privileges in order to perform this operation.

add assignments...
    Adds an entry with the data given in assignments. The user must be logged in and have hero privileges in order to perform this operation.

me  A short form of the query command which displays all fields of the currently logged-in user's entry.

resolve_email user
    Returns the PH-resolved email address for user.

public_email alias
    Returns the advertised email address for alias.

resolve_www user
    Returns the PH-resolved URL for user.

public_www alias
    Returns the advertised URL for alias.

SELECTING ENTRIES
The query, change, and delete commands select the entries which they operate on based on selectors. The selectors are a list of one or more criteria which are used by the server to select entries. When multiple selectors are listed, only entries which match all of the selectors will be selected. Each selector is composed of a value, preceded by an optional field and operator. If the field and operator are given, the selector matches entries whose data for the given field matches the given value. If no field and operator are given, the default fields are checked, which are usually "name" and "nickname". The only universally understood operator is '=', but some servers support '~', '<', and '>'. Certain special symbols, called "wildcard" characters, can be used in the value if the exact spelling is unknown. The '*' character is used in place of zero or more characters, the '+' character in place of one or more unknown characters, and the '?' character can be used when exactly one character is unknown. In addition, if the unknown character can be one of a limited set this can be specified by surrounding the set with brackets, e.g., [ei] means that in that place an 'e' or an 'i' would match. Here are a few examples of selectors:

alias=smith
    Select entries whose alias field is set to smith.

john smith
    Select entries whose name or nickname fields match john and smith.

alias=smi* name=john
    Select entries whose alias field starts with smi and whose name or nickname fields contain john.

Many servers apply limits on computation time and or on the number of entries returned, to prevent mailing list generation and/or to minimize performance problems. Therefore, it is often advisable to be as specific as possible in identifying an entry.

ASSIGNING VALUES
The change, make, and add commands set specific fields to specific values on the server based on a list of one or more assignments. All of the listed assignments are performed on all of the selected entries. Each assignment is composed of a field name, the '=' character, and a value. This syntax is similar to the selector syntax, but it is somewhat more rigid. Assignments cannot omit the field name, cannot use operators other then '=', and cannot use wildcard characters. Here are a few examples of assignments:

email=j-smith@students.uiuc.edu
    Sets the email field to j-smith@students.uiuc.edu.

www=http://www.students.uiuc.edu/~j-smith/
    Sets the www field to http://www.students.uiuc.edu/~j-smith/.

CLIENT OPTIONS
Client options are settable using the option command described above. The following client options are supported. The default value is listed in parenthesis next to each option.

authtype (password)
    Defines the authentication mechanism used to login to the PH server. Supported mechanisms are password, email, and clear. (The clear method is not recommended because it is inherently insecure.)

confirmedits (off)
    This is a boolean option. If on, nph will ask for confirmation before applying the change during an edit command.

debug (off)
    This is a boolean option. If on, all communication between the client and server will be displayed.

defaultfield (not set by default)
    Defines the default field for field selectors which do not specify a field. If unset, the default field configured on the server is used (usually name and nickname).

editor ($EDITOR)
    Defines the editor to use for edit commands. If the first character is a '$', the value is obtained from the named environment variable.

pager ($PAGER)
    Defines an external pager program (such as more or less) to use for query, me, fields, and status commands. If the first character is a '$', the value is obtained from the named environment variable.

returnfields (not set by default)
    Set the list of fields which are returned for queries which do not have a return clause. For multiple fields, specify a quoted string of space-delimited field names. If this option is not set and no return clause is given, only fields marked with the Default attribute are returned by the server.

server (none)
    Defines which PH server (and optionally, which port) to connect to. Changing this setting will imediately disconnect from the current server and connect to the newly-specified server.

canonicaladdrs (on)
    This is a boolean option. If on, advertised addresses are printed for the email and www fields instead of the actual values.

usepager (on)
    This is a boolean option. If on, the pager specified by the pager option will be used for the query, me, fields, and status commands. Otherwise, the output of these commands will be sent to stdout.

usereservedport (off)
    Connect to the PH server from a port below 1024. This is necessary in order to use the email authentication method (described above). However, nph must be running as root in order to do this, which is not recommended.

STARTUP FILES
On startup, nph will first read the /usr/local/etc/nphrc file, and then the invoking user's ${HOME}/.nphrc file. These files can be used to set defaults for nph options. The file must consist of assignments of the form option=value, one per line. Blank lines are ignored, as is any text on the same line following a '#' character. nph will also read the /usr/local/etc/ph_servers file at startup for a default list of known PH servers at different sites.

REDIRECTING OUTPUT
The standard shell expressions ">", ">>", and "|" can be used at the end of any nph command to redirect the output to a file or program. If the output of a query, me, fields, or status command is redirected, it is not piped to the pager regardless of the setting of the usepager option.

FILES
/usr/local/etc/nphrc
/usr/local/etc/ph_server
${HOME}/.nphrc
${HOME}/.nphrc.*

SEE ALSO
ph_open(3)
The nph Homepage (http://www.feep.net/nph/)

AUTHOR
Mark D. Roth <roth@feep.net>