DragonFly On-Line Manual Pages
nph(1) Directory Services 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>
University of Illinois Oct 2002 nph(1)