cirno/plan9port
1
0
Fork 0
mirror of https://github.com/9fans/plan9port.git synced 2025-01-12 11:10:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

new man pages

Browse source
This commit is contained in:
rsc 2005-02-11 19:21:47 +00:00
parent 7442c7ac4b
commit d93fca6a7a
21 changed files with 3089 additions and 31 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
man/man1/9p.1
View file

@ -24,6 +24,9 @@
.I addr
]
.B write
[
.B -l
]
.I path
.br
.B 9p
@ -56,7 +59,12 @@ to standard output
.TP
.B write
write data on standard input to
.I path
.IR path ;
the
.B -l
option causes
.I write
to write one line at a time
.TP
.BR readfd ", " writefd
like

1
man/man1/INDEX
View file

@ -39,6 +39,7 @@ iconv crop.1
cvs cvs.1
date date.1
db db.1
stack db.1
dc dc.1
delatex deroff.1
deroff deroff.1

10
man/man1/install.1
View file

@ -63,6 +63,16 @@ checks whether the running system uses NPTL and sets
in
.B \*9/config
accordingly.
The file
.B \*9/LOCAL.config
is appended to
.B config
after this auto-detection and can be used to override the choices.
If
.B LOCAL.config
contains a line
.B WSYS=nowsys
then the system is built without using X11.
.SH FILES
.TP
.B \*9/lib/moveplan9.files

443
man/man1/ndb.1 Normal file
View file

@ -0,0 +1,443 @@
.TH NDB 1
.SH NAME
ndbquery, ndbmkhash, ndbmkdb, ndbipquery, ndbmkhosts \- network database
.SH SYNOPSIS
.B ndbquery
[
.B -f
.I dbfile
]
.I "attr value"
[
.I rattr
]
.br
.B ndbipquery
.I "attr value"
.I rattr...
.br
.B ndbmkhash
.I "file attr"
.br
.B ndbmkdb
.SH DESCRIPTION
The network database holds administrative information used by
.I authdial
(see
.IR authsrv (3))
and
.I secstored (1).
.PP
.I Ndbquery
searches the database for an attribute of type
.I attr
and value
.IR value .
If
.I rattr
is not specified, all entries matched by the search are returned.
If
.I rattr
is specified, the value of the first pair with attribute
.I rattr
of all the matched entries is returned.
.PP
.I Ndbipquery
uses
.I ndbipinfo
(see
.IR ndb (2))
to search for the values of the attributes
.I rattr
corresponding to the system
with entries of attribute type
.I attr
and
value
.IR value .
.PP
.I Ndbmkhash
creates a hash file for all entries with attribute
.I attr
in database file
.IR file .
The hash files are used by
.I ndbquery
and by the ndb library routines.
.\" .PP
.\" .I Ndb/cs
.\" is a server used by
.\" .IR dial (2)
.\" to translate network names.
.\" It is started at boot time.
.\" It finds out what networks are configured
.\" by looking for
.\" .B /net/*/clone
.\" when it starts.
.\" It can also be told about networks by writing
.\" to
.\" .B /net/cs
.\" a message of the form:
.\" .IP
.\" .B "add net1 net2 ..."
.\" .PP
.\" .I Ndb/cs
.\" also sets the system name in
.\" .B /dev/sysname
.\" if it can figure it out.
.\" The options are:
.\" .TP
.\" .B -f
.\" supplies the name of the data base file to use,
.\" default
.\" .BR /lib/ndb/local .
.\" .TP
.\" .B -x
.\" specifies the mount point of the
.\" network.
.\" .TP
.\" .B -n
.\" causes cs to do nothing but set the system name.
.\" .PP
.\" .I Ndb/csquery
.\" can be used to query
.\" .I ndb/cs
.\" to see how it resolves addresses.
.\" .I Ndb/csquery
.\" prompts for addresses and prints out what
.\" .I ndb/cs
.\" returns.
.\" .I Server
.\" defaults to
.\" .BR /net/cs .
.\" If any
.\" .I addrs
.\" are specified,
.\" .I ndb/csquery
.\" prints their translations and immediately exits.
.\" The exit status will be nil only if all addresses
.\" were successfully translated
.\" The
.\" .B -s
.\" flag sets exit status without printing any results.
.\" .PP
.\" .I Ndb/dns
.\" is a server used by
.\" .I ndb/cs
.\" and by remote systems to translate Internet domain names.
.\" .I Ndb/dns
.\" is started at boot time.
.\" By default
.\" .I dns
.\" serves only requests written to
.\" .BR /net/dns .
.\" The options are:
.\" .TP
.\" .B -f
.\" supplies the name of the data base file to use,
.\" default
.\" .BR /lib/ndb/local .
.\" .TP
.\" .B -x
.\" specifies the mount point of the
.\" network.
.\" .TP
.\" .B -s
.\" also answer domain requests sent to UDP port 53.
.\" .TP
.\" .B -n
.\" whenever a zone that we serve changes, send UDP NOTIFY
.\" messages to any dns slaves for that zone.
.\" .TP
.\" .B -z
.\" whenever we receive a UDP NOTIFY message, run
.\" .I program
.\" with the domain name of the area as its argument.
.\" .TP
.\" .B -r
.\" defer to other servers to resolve queries.
.\" .PP
.\" When the
.\" .B -r
.\" option is specified, the servers used come from the
.\" .I dns
.\" attribute in the database. For example, to specify a set of dns servers that
.\" will resolve requests for systems on the network
.\" .IR mh-net :
.\" .EX
.\"
.\" ipnet=mh-net ip=135.104.0.0 ipmask=255.255.0.0
.\" dns=ns1.cs.bell-labs.com
.\" dns=ns2.cs.bell-labs.com
.\" dom=ns1.cs.bell-labs.com ip=135.104.1.11
.\" dom=ns2.cs.bell-labs.com ip=135.104.1.12
.\"
.\" .EE
.\" .PP
.\" The server for a domain is indicated by a database entry containing
.\" both a
.\" .I dom
.\" and a
.\" .I ns
.\" attribute.
.\" For example, the entry for the Internet root is:
.\" .EX
.\"
.\" dom=
.\" ns=A.ROOT-SERVERS.NET
.\" ns=B.ROOT-SERVERS.NET
.\" ns=C.ROOT-SERVERS.NET
.\" dom=A.ROOT-SERVERS.NET ip=198.41.0.4
.\" dom=B.ROOT-SERVERS.NET ip=128.9.0.107
.\" dom=C.ROOT-SERVERS.NET ip=192.33.4.12
.\"
.\" .EE
.\" The last three lines provide a mapping for the
.\" server names to their ip addresses. This is only
.\" a hint and will be superseded from whatever is learned
.\" from servers owning the domain.
.\" .PP
.\" You can also serve a subtree of the domain name space from the local
.\" database. You indicate subtrees that you'ld like to serve by
.\" adding an
.\" .B soa=
.\" attribute to the root entry.
.\" For example, the Bell Labs CS research domain is:
.\" .EX
.\"
.\" dom=cs.bell-labs.com soa=
.\" refresh=3600 ttl=3600
.\" ns=plan9.bell-labs.com
.\" ns=ns1.cs.bell-labs.com
.\" ns=ns2.cs.bell-labs.com
.\" mb=presotto@plan9.bell-labs.com
.\" mx=mail.research.bell-labs.com pref=20
.\" mx=plan9.bell-labs.com pref=10
.\" dnsslave=nslocum.cs.bell-labs.com
.\" dnsslave=vex.cs.bell-labs.com
.\"
.\" .EE
.\" Here, the
.\" .B mb
.\" entry is the mail address of the person responsible for the
.\" domain (default
.\" .BR postmaster ).
.\" The
.\" .B mx
.\" entries list mail exchangers for the domain name and
.\" .B refresh
.\" and
.\" .B ttl
.\" define the area refresh interval and the minimum TTL for
.\" records in this domain.
.\" The
.\" .B dnsslave
.\" entries specify slave DNS servers that should be notified
.\" when the domain changes. The notification also requires
.\" the
.\" .B -n
.\" flag.
.\" .PP
.\" You can also serve reverse lookups (returning the name that
.\" goes with an IP address) by adding an
.\" .B soa=
.\" attribute to the entry defining the root of the reverse space.
.\" For example, to provide reverse lookup for all addresses in
.\" starting with 135.104 you must have a record like:
.\" .EX
.\"
.\" dom=104.135.in-addr.arpa soa=
.\" refresh=3600 ttl=3600
.\" ns=plan9.bell-labs.com
.\" ns=ns1.cs.bell-labs.com
.\" ns=ns2.cs.bell-labs.com
.\" .EE
.\" Notice the form of the reverse address, i.e., it's the bytes of the
.\" address range you are serving reversed and with
.\" .B .in-addr.arpa
.\" appended. This is a standard form for a domain name in an IPv4 PTR record.
.\" .PP
.\" If such an entry exists in the database, reverse addresses will
.\" automaticly be generated from any IP addresses in the database
.\" that are under this root. For example
.\" .EX
.\"
.\" dom=ns1.cs.bell-labs.com ip=135.104.1.11
.\" .EE
.\" will automaticly create both forward and reverse entries for
.\" .B ns1.cs.bell-labs.com .
.\" Unlike other DNS servers, there's no way to generate
.\" inconsistent forward and reverse entries.
.\" .PP
.\" Delegation of a further subtree to another set of name servers
.\" is indicated by an
.\" .B soa=delegated
.\" attribute.
.\" .EX
.\"
.\" dom=bignose.cs.research.bell-labs.com
.\" soa=delegated
.\" ns=anna.cs.research.bell-labs.com
.\" ns=dj.cs.research.bell-labs.com
.\"
.\" .EE
.\" Nameservers within the delegated domain (as in this example)
.\" must have their IP addresses listed elsewhere in
.\" .I ndb
.\" files.
.\" .PP
.\" Wild-carded domain names can also be used.
.\" For example, to specify a mail forwarder for all Bell Labs research systems:
.\" .EX
.\"
.\" dom=*.research.bell-labs.com
.\" mx=research.bell-labs.com
.\"
.\" .EE
.\" `Cname' aliases may be established by adding a
.\" .B cname
.\" attribute giving the real domain name;
.\" the name attached to the
.\" .B dom
.\" attribute is the alias.
.\" `Cname' aliases are severely restricted;
.\" the aliases may have no other attributes than
.\" .B dom
.\" and are daily further restricted in their use by new RFCs.
.\" .EX
.\"
.\" cname=anna.cs.research.bell-labs.com dom=www.cs.research.bell-labs.com
.\"
.\" .EE
.\" .I Ndb/dnsquery
.\" can be used to query
.\" .I ndb/dns
.\" to see how it resolves requests.
.\" .I Ndb/dnsquery
.\" prompts for commands of the form
.\" .IP
.\" .I "domain-name request-type"
.\" .LP
.\" where
.\" .I request-type
.\" can be
.\" .BR ip ,
.\" .BR mx ,
.\" .BR ns ,
.\" .BR cname ,
.\" .BR ptr ....
.\" In the case of the inverse query type,
.\" .BR ptr ,
.\" .I dnsquery
.\" will reverse the ip address and tack on the
.\" .B .in-addr.arpa
.\" for you.
.\" .PP
.\" .I Ndb/dnsdebug
.\" is like
.\" .I ndb/dnsquery
.\" but bypasses the local server.
.\" It communicates via UDP with the domain name servers
.\" in the same way that the local resolver would and displays
.\" all packets received.
.\" The query can be specified on the command line or
.\" can be prompted for.
.\" The queries look like those of
.\" .I ndb/dnsquery
.\" with one addition.
.\" .I Ndb/dnsdebug
.\" can be directed to query a particular name server by
.\" the command
.\" .BI @ name-server\f1.
.\" From that point on, all queries go to that name server
.\" rather than being resolved by
.\" .IR dnsdebug .
.\" The
.\" .B @
.\" command returns query resolution to
.\" .IR dnsdebug .
.\" Finally, any command preceded by a
.\" .BI @ name-server
.\" sets the name server only for that command.
.\" .PP
.\" Normally
.\" .I dnsdebug
.\" uses the
.\" .B /net
.\" interface and the database file
.\" .BR /lib/ndb/local.
.\" The
.\" .B -x
.\" option directs
.\" .I dnsdebug
.\" to use the
.\" .B /net.alt
.\" interface and
.\" .B /lib/ndb/external
.\" file.
.\" The
.\" .B -r
.\" option is the same as for
.\" .IR ndb/dns .
.PP
.I Ndbmkdb
is used in concert with
.IR awk (1)
scripts to convert
uucp systems files and IP host files
into database files.
It is very specific to the situation at Murray Hill.
.PP
When the database files change underfoot,
running programs
track them properly. Nonetheless, to keep the database searches efficient
it is necessary to run
.I ndbmkhash
whenever the files are modified.
It may be profitable to control this by a frequent
.IR cron (8)
job.
.PP
.I Ndbmkhosts
generates a BSD style
.BR hosts ,
.BR hosts.txt ,
and
.B hosts.equiv
files from ndb data base files specified on the
command line (default
.B \*9/ndb/local
and
.BR \*9/ndb/friends ).
It only processes hosts whose domain names end in
.IR domname .
The output files are named
.BI db. domname \fR,
.BI equiv. domname \fR,
and
.BI txt. domname \fR.
For historical reasons, the default
.I domname
is
.BR research.att.com.
.SH EXAMPLE
.IP
.EX
% ndbquery sys helix
sys=helix dom=helix.research.bell-labs.com bootf=/mips/9powerboot
ip=135.104.117.31 ether=080069020427
proto=il
.EE
.SH FILES
.TP
.B \*9/ndb/local
first database file searched
.TP
.B \*9/ndb/local.*
hash files for
.B \*9/ndb/local
.SH SOURCE
.B \*9/src/cmd/ndb
.SH SEE ALSO
.IR ndb (3),
.IR ndb (7)

20
man/man1/netkey.1 Normal file
View file

@ -0,0 +1,20 @@
.TH NETKEY 1
.SH NAME
netkey \- challenge-response authentication
.SH SYNOPSIS
.PP
.B netkey
.SH DESCRIPTION
.PP
.I Netkey
prompts for a password to encrypt network challenges.
It is a substitute for a SecureNet box.
.SH SOURCE
.B \*9/src/cmd/netkey.c
.SH "SEE ALSO"
.IR encrypt (3)
.PP
Robert Morris and Ken Thompson,
``UNIX Password Security,''
.I AT&T Bell Laboratories Technical Journal
Vol 63 (1984), pp. 1649-1672

6
man/man1/sam.1
View file

@ -41,6 +41,12 @@ which editing commands apply\(emwhereupon its menu entry is printed.
The options are
.TF -rmachine
.TP
.B -a
Autoindent. In this mode, when a newline character is typed
in the terminal interface,
.I samterm
copies leading white space on the current line to the new line.
.TP
.B -d
Do not `download' the terminal part of
.IR sam .

42
man/man1/secstore.1
View file

@ -1,6 +1,6 @@
.TH SECSTORE 1
.SH NAME
aescbc, secstore, ipso \- secstore commands
aescbc, secstore \- secstore commands
.SH SYNOPSIS
.B secstore
[
@ -42,15 +42,14 @@ aescbc, secstore, ipso \- secstore commands
-d
.I <ciphertext
.I >cleartext
.PP
.B ipso
[
.B -a -e -l -f -s
] [
.I file
\&...
]
.PP
.\" .PP
.\" .B ipso
.\" [
.\" .B -a -e -l -f -s
.\" ] [
.\" .I file
.\" \&...
.\" ]
.SH DESCRIPTION
.PP
.I Secstore
@ -92,38 +91,37 @@ Option
.B -i
says that the password should be read from standard input
instead of from
.BR /dev/cons .
.BR /dev/tty .
.PP
Option
.B -n
says that the password should be read from NVRAM
(see
.IR authsrv (2))
instead of from
.BR /dev/cons .
This option is unsupported.
.BR /dev/tty .
.PP
The server is
.BR tcp!$auth!5356 ,
.BR tcp!$auth!secstore ,
or the server specified by option
.BR -s .
.PP
For example, to add a secret to the file read by
.IR factotum (4)
at startup, open a new window, type
.IR factotum (4),
run
.sp
.EX
% ramfs -p; cd /tmp
% cd somewhere-private
% auth/secstore -g factotum
secstore password:
% echo 'key proto=apop dom=x.com user=ehg !password=hi' >> factotum
% auth/secstore -p factotum
secstore password:
% read -m factotum > /mnt/factotum/ctl
% cat factotum | 9p write -l factotum/ctl
.EE
.PP
and delete the window.
The first line creates an ephemeral memory-resident workspace,
invisible to others and automatically removed when the window is deleted.
The next three commands fetch the persistent copy of the secrets,
The middle commands fetch the persistent copy of the secrets,
append a new secret,
and save the updated file back to secstore.
The final command loads the new secret into the running factotum.
@ -199,7 +197,7 @@ block chaining (CBC) mode.
.B \*9/src/cmd/secstore
.SH SEE ALSO
.IR factotum (4),
Plan 9's \fIsecstore\fR(8)
.IR secstored (1)
.SH BUGS
There is deliberately no backup of files on the secstore, so
.B -r

64
man/man1/secstored.1 Normal file
View file

@ -0,0 +1,64 @@
.TH SECSTORED 8
.SH NAME
secstored, secuser \- secstore commands
.SH SYNOPSIS
.br
.B secstored
[-R]
[-S servername]
[-s tcp!*!5356]
[-x mountpoint]
.br
.B secuser
[-v]
username
.br
.PP
.SH DESCRIPTION
.PP
.I Secstored
serves requests from
.IR secstore (1).
The
.B -R
option supplements the password check with a
call to a RADIUS server, for checking hardware
tokens or other validation.
The
.BR -x mountpoint
option specifies an alternative to the default network
.BR /net .
.PP
.I Secuser
is an administrative command that runs on the
secstore machine, normally the authserver,
to create new accounts and
to change status on existing accounts.
It prompts for account information such as
password and expiration date, writing to
.BR \*9/secstore/who/$uid .
The
.B \*9/secstore
directory should be created mode 770 for the userid
or groupid of the secstored process.
.PP
By default,
.I secstored
warns the client if no account exists.
If you prefer to obscure this information, use
.I secuser
to create an account
.BR FICTITIOUS .
.SH FILES
.B \*9/secstore/who/$uid
secstore account name, expiration date, verifier
.br
.B \*9/secstore/store/$uid/
users' files
.br
.B \*9/ndb/auth
for mapping local userid to RADIUS userid
.SH SOURCE
.B \*9/src/cmd/secstore
.SH SEE ALSO
.IR secstore (1)

166
man/man1/tar.1 Normal file
View file

@ -0,0 +1,166 @@
.TH TAR 1
.SH NAME
tar \- archiver
.SH SYNOPSIS
.B tar
.I key
[
.I file ...
]
.SH DESCRIPTION
.PP
.I Tar
saves and restores file trees.
It is most often used to transport a tree of files from one
system to another.
The
.I key
is a string that contains
at most one function letter plus optional modifiers.
Other arguments to the command are names of
files or directories to be dumped or restored.
A directory name implies all the contained
files and subdirectories (recursively).
.PP
The function is one of the following letters:
.TP
.B c
Create a new archive with the given files as contents.
.TP
.B r
The named files
are appended to the archive.
.TP
.B t
List all occurrences of each
.I file
in the archive, or of all files if there are no
.I file
arguments.
.TP
.B x
Extract the named files from the archive.
If a file is a directory, the directory is extracted recursively.
Modes are restored if possible.
If no file argument is given, extract the entire archive.
If the archive contains multiple entries for a file,
the latest one wins.
.PP
The modifiers are:
.TP
.B f
Use the next argument as the name of the archive instead of
the default standard input (for keys
.B x
and
.BR t )
or standard output (for keys
.B c
and
.BR r ).
.TP
.B g
Use the next (numeric) argument as the group id for files in
the output archive.
.TP
.B k
(keep)
Modifies the behavior of
.B x
not to extract files which already exist.
.TP
.B m
Do not set the modification time on extracted files.
This is the default behavior; the flag exists only for compatibility with other tars.
.TP
.B p
Create archive in POSIX ustar format,
which raises the maximum pathname length from 100 to 256 bytes.
Ustar archives are recognised automatically by
.I tar
when reading archives.
This is the default behavior; the flag exists only for backwards compatibility
with older versions of tar.
.TP
.B P
Do not generate the POSIX ustar format.
.TP
.B R
When extracting, ignore leading slash on file names,
i.e., extract all files relative to the current directory.
.TP
.B T
Modifies the behavior of
.B x
to set the modified time
of each file to that specified in the archive.
.TP
.B u
Use the next (numeric) argument as the user id for files in
the output archive. This is only useful when moving files to
a non-Plan 9 system.
.TP
.B v
(verbose)
Print the name of each file treated
preceded by the function letter.
With
.BR t ,
give more details about the
archive entries.
.TP
.B z
Operate on compressed tar archives.
The type of compression is inferred from the file name extension:
.IR gzip (1)
for
.B .tar.gz
and
.BR .tgz ;
.I bzip2
(see
.IR gzip (1))
for
.BR .tar.bz ,
.BR .tbz ,
.BR .tar.bz2 ,
and
.BR .tbz2 ;
.I compress
(not distributed)
for
.B .tar.Z
and
.BR .tz .
If no extension matches,
.I gzip
is used.
The
.B z
flag is unnecessary (but allowed) when using the
.B t
and
.B x
verbs on archives with recognized extensions.
.SH EXAMPLES
.I Tar
can be used to copy hierarchies thus:
.IP
.EX
@{cd fromdir && tar cp .} | @{cd todir && tar xT}
.EE
.SH SOURCE
.B \*9/src/cmd/tar.c
.SH SEE ALSO
.IR ar (1),
.IR bundle (1)
.SH BUGS
There is no way to ask for any but the last
occurrence of a file.
.br
File path names are limited to
100 characters
(256 when using ustar format).
.br
The tar format allows specification of links and symbolic links,
concepts foreign to Plan 9: they are ignored.

10
man/man3/9p.3
View file

@ -46,6 +46,7 @@ typedef struct Srv {
void (*destroyfid)(Fid *fid);
void (*destroyreq)(Req *r);
void (*start)(Srv *s);
void (*end)(Srv *s);
void* aux;
@ -308,7 +309,7 @@ These constraints are checked while the server executes.
If a service function fails to do something it ought to have,
.I srv
will call
.I endsrv
.I end
and then abort.
.TP
.I Auth
@ -654,6 +655,7 @@ has been sent.
.PP
.IR Destroyfid ,
.IR destroyreq ,
.IR start ,
and
.I end
are auxiliary functions, not called in direct response to 9P requests.
@ -684,6 +686,12 @@ is called to allow the program to dispose of the
.IB r -> aux
pointer.
.TP
.I Start
Before the 9P service loop begins, the service proc calls
.I start
so that the server can run any initialization that must be
done from inside the service proc.
.TP
.I End
Once the 9P service loop has finished
(end of file been reached on the service pipe

30
man/man3/9pclient.3
View file

@ -1,6 +1,6 @@
.TH 9PCLIENT 3
.SH NAME
CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fswrite \- 9P client library
CFid, CFsys, fsinit, fsmount, fsroot, fssetroot, fsunmount, nsmount, fsversion, fsauth, fsattach, fsclose, fscreate, fsdirread, fsdirreadall, fsdirstat, fsdirfstat, fsdirwstat, fsdirfwstat, fsopen, fsopenfd, fspread, fspwrite, fsread, fsreadn, fsseek, fswrite \- 9P client library
.SH SYNOPSIS
.B #include <u.h>
.PP
@ -27,6 +27,9 @@ void fsunmount(CFsys *fsys)
CFsys* fsinit(int fd)
.PP
.B
CFsys* nsinit(char *name)
.PP
.B
int fsversion(CFsys *fsys, int msize, char *version, int nversion)
.PP
.B
@ -85,6 +88,9 @@ int fsdirfwstat(CFid *fid, Dir *d)
.PP
.B
int fsopenfd(CFsys *fs, char *path, int mode)
.PP
.B
CFsys* nsopen(char *name, char *aname, char *path, int mode)
.SH DESCRIPTION
The
.I 9pclient
@ -121,6 +127,7 @@ returns the
corresponding to this root.
.PP
.IR Fsinit ,
.IR nsinit ,
.IR fsversion ,
.IR fsauth ,
.IR fsattach ,
@ -135,7 +142,12 @@ and
allocates a new
.B CFsys*
corresponding to a 9P conversation on the file descriptor
.IR fd .
.I fd
and then calls
.IR fsversion
to initialize the connection.
.I Nsinit
does the same for name space services.
.I Fsversion
executes a
.IR version (9p)
@ -328,11 +340,23 @@ the only signal of a read or write error is the closing of the pipe.
The file descriptor remains valid even after the
.B CFsys
is unmounted.
.PP
.I Nsopen
opens a single file on a name space server: it runs
.IR nsmount ,
.IR fsopen ,
and then
.IR fsunmount .
.SH SOURCE
.B \*9/src/lib9pclient
.SH SEE ALSO
.IR intro (4),
.IR intro (9p)
.IR intro (9p),
.I fsaopen
and
.I nsaopen
in
.IR auth (3)
.SH BUGS
The implementation
should use a special version string to distinguish between

3
man/man3/INDEX
View file

@ -982,6 +982,8 @@ runestrncmp runestrcat.3
runestrncpy runestrcat.3
runestrrchr runestrcat.3
runestrstr runestrcat.3
search searchpath.3
searchpath searchpath.3
hmac_md5 sechash.3
hmac_sha1 sechash.3
md4 sechash.3
@ -1116,6 +1118,7 @@ threadsetgrp thread.3
threadsetname thread.3
threadsetstate thread.3
threadspawn thread.3
threadspawnl thread.3
threadwaitchan thread.3
yield thread.3
nsec time.3

422
man/man3/auth.3 Normal file
View file

@ -0,0 +1,422 @@
.TH AUTH 3
.SH NAME
auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users
.SH SYNOPSIS
.nf
.PP
.ft L
#include <u.h>
#include <libc.h>
#include <auth.h>
.fi
.ta 11n +4n +4n +4n +4n +4n +4n
.\" .PP
.\" .B
.\" int newns(char *user, char *nsfile);
.\" .PP
.\" .B
.\" int addns(char *user, char *nsfile);
.\" .PP
.\" .B
.\" int amount(int fd, char *old, int flag, char *aname);
.\" .PP
.\" .B
.\" int login(char *user, char *password, char *namespace);
.\" .PP
.\" .B
.\" int noworld(char *user);
.PP
.B
AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...);
.PP
.B
AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey,
.br
.B char *params);
.PP
.B
AuthRpc* auth_allocrpc(void);
.PP
.B
void auth_freerpc(AuthRpc *rpc);
.PP
.B
uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n);
.PP
.B
int auth_getkey(char *proto, char *dom);
.PP
.B
int (*amount_getkey)(char*, char*);
.PP
.B
void auth_freeAI(AuthInfo *ai);
.PP
.B
int auth_chuid(AuthInfo *ai, char *ns);
.PP
.B
Chalstate* auth_challenge(char *fmt, ...);
.PP
.B
AuthInfo* auth_response(Chalstate*);
.PP
.B
void auth_freechal(Chalstate*);
.PP
.B
int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...);
.PP
.B
AuthInfo* auth_userpasswd(char*user, char*password);
.PP
.B
UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);
.PP
.B
AuthInfo* auth_getinfo(AuthRpc *rpc);
.PP
.B
#include <9pclient.h>
.PP
.B
CFsys* fsamount(int fd, char *aname);
.PP
.B
CFsys* nsamount(char *name, char *aname);
.SH DESCRIPTION
.PP
This library, in concert with
.IR factotum (4),
is used to authenticate users.
It provides the primary interface to
.IR factotum .
.\" .PP
.\" .I Newns
.\" builds a name space for
.\" .IR user .
.\" It opens the file
.\" .I nsfile
.\" .RB ( /lib/namespace
.\" is used if
.\" .I nsfile
.\" is null),
.\" copies the old environment, erases the current name space,
.\" sets the environment variables
.\" .B user
.\" and
.\" .BR home ,
.\" and interprets the commands in
.\" .IR nsfile .
.\" The format of
.\" .I nsfile
.\" is described in
.\" .IR namespace (6).
.\" .PP
.\" .I Addns
.\" also interprets and executes the commands in
.\" .IR nsfile .
.\" Unlike
.\" .I newns
.\" it applies the command to the current name space
.\" rather than starting from scratch.
.\" .PP
.\" .I Amount
.\" is like
.\" .I mount
.\" but performs any authentication required.
.\" It should be used instead of
.\" .I mount
.\" whenever the file server being mounted requires authentication.
.\" See
.\" .IR bind (2)
.\" for a definition of the arguments to
.\" .I mount
.\" and
.\" .IR amount .
.\" .PP
.\" .I Login
.\" changes the user id of the process
.\" .I user
.\" and recreates the namespace using the file
.\" .I namespace
.\" (default
.\" .BR /lib/nnamespace ).
.\" It uses
.\" .I auth_userpassword
.\" and
.\" .IR auth_chuid .
.\" .PP
.\" .I Noworld
.\" returns 1 if the user is in the group
.\" .B noworld
.\" in
.\" .BR /adm/users .
.\" Otherwise, it returns 0.
.\" .I Noworld
.\" is used by telnetd and ftpd to provide sandboxed
.\" access for some users.
.PP
The following routines use the
.B AuthInfo
structure returned after a successful authentication by
.IR factotum (4).
.PP
.ne 8
.EX
.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
typedef struct
{
char *cuid; /* caller id */
char *suid; /* server id */
char *cap; /* capability */
int nsecret; /* length of secret */
uchar *secret; /* secret */
} AuthInfo;
.EE
.sp
The fields
.B cuid
and
.B suid
point to the authenticated ids of the client and server.
.B Cap
is a capability returned only to the server.
It is meaningful only on Plan 9.
.\" It can be passed to the
.\" .IR cap (3)
.\" device to change the user id of the process.
.B Secret
is an
.BR nsecret -byte
shared secret that can be used by the client and server to
create encryption and hashing keys for the rest of the
conversation.
.PP
.I Auth_proxy
proxies an authentication conversation between a remote
server reading and writing
.I fd
and a
.I factotum
file, as opened by
.IR auth_allocrpc.
An
.B sprint
(see
.IR print (2))
of
.I fmt
and the variable arg list yields a key template (see
.IR factotum (4))
specifying the key to use.
The template must specify at least the protocol (
.BI proto= xxx )
and the role (either
.B role=client
or
.BR role=server ).
.I Auth_proxy
either returns an allocated
.B AuthInfo
structure, or sets the error string and
returns nil.
.PP
.I Fauth_proxy
can be used instead of
.I auth_proxy
if a single connection to
.I factotum
will be used for multiple authentications.
This is necessary, for example, for
.I newns
which must open the
.I factotum
file before wiping out the namespace.
.I Fauth_proxy
takes as an argument a pointer to an
.B AuthRpc
structure which contains an fd for an open connection to
.I factotum
in addition to storage and state information for
the protocol.
An
.B AuthRpc
structure is obtained by calling
.IR auth_allocrpc .
.I Auth_allocrpc
arranges a connection to
.IR factotum ,
either by opening
.B /mnt/factotum/rpc
or by using
.IR 9pclient (3)
to connect to a
.B factotum
service posted in the current name space.
The returned connection
is freed using
.IR auth_freerpc .
Individual commands can be sent to
.IR factotum (4)
by invoking
.IR auth_rpc .
.PP
Both
.I auth_proxy
and
.I fauth_proxy
take a pointer to a routine,
.IR getkey ,
to invoke should
.I factotum
not posess a key for the authentication. If
.I getkey
is nil, the authentication fails.
.I Getkey
is called with a key template for the desired
key.
We have provided a generic routine,
.IR auth_getkey ,
which queries the user for
the key information and passes it to
.IR factotum .
This is the default for the global variable,
.IR amount_getkey ,
which holds a pointer to the key prompting routine used by
.IR amount .
.PP
.I Auth_chuid
uses the
.B cuid
and
.B cap
fields of an
.B AuthInfo
structure to change the user id of the current
process and uses
.IR ns ,
default
.BR /lib/namespace ,
to build it a new name space.
.PP
.I Auth_challenge
and
.I auth_response
perform challenge/response protocols with
.IR factotum .
State between the challenge and response phase are
kept in the
.B Chalstate
structure:
.sp
.EX
struct Chalstate
{
char *user;
char chal[MAXCHLEN];
int nchal;
void *resp;
int nresp;
/* for implementation only */
int afd;
AuthRpc *rpc;
char userbuf[MAXNAMELEN];
int userinchal;
};
.EE
.sp
.I Auth_challenge
requires a key template generated by an
.B sprint
of
.I fmt
and the variable arguments. It must contain the protocol
(\fBproto=\fIxxx\fR)
and depending on the protocol, the user name (
.BI user= xxx \fR).\fP
.B P9cr
and
.B vnc
expect the user specified as an attribute in
the key template and
.BR apop ,
.BR cram ,
and
.BR chap
expect it in the
.B user
field of the arg to
.IR auth_response .
For all protocols, the response is returned
to
.I auth_response
in the
.I resp
field of the
.BR Chalstate .
.I Chalstate.nresp
must be the length of the response.
.PP
Supply to
.I auth_respond
a challenge string and the fmt and args specifying a key,
and it will use
.I factotum
to return the proper user and response.
.PP
.I Auth_userpasswd
verifies a simple user/password pair.
.I Auth_getuserpasswd
retrieves a user/password pair from
.I factotum
if permitted.
.PP
.I Auth_getinfo
reads an
.B AuthInfo
message from factotum
and converts it into a structure. It is only
used by the other routines in this library when
communicating with
.IR factotum .
.PP
.ne 8
.EX
.ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
typedef struct UserPasswd {
char *user;
char *passwd;
} UserPasswd;
.EE
.sp
.PP
.I Auth_freeAI
is used to free an
.B AuthInfo
structure returned by one of these routines.
Similary
.I auth_freechal
frees a challenge/response state.
.PP
.I Fsamount
and
.I nsamount
are like
.I fsmount
and
.I nsmount
(see
.IR 9pclient (3))
but use
.I factotum
to authenticate to the file servers.
.SH SOURCE
.B \*9/src/libauth
.SH SEE ALSO
.IR factotum (4),
.IR authsrv (3)
.SH DIAGNOSTICS
These routines set
.IR errstr .

222
man/man3/authsrv.3 Normal file
View file

@ -0,0 +1,222 @@
.TH AUTHSRV 3
.SH NAME
authdial, passtokey, nvcsum, readnvram, convT2M, convM2T, convTR2M, convM2TR, convA2M, convM2A, convPR2M, convM2PR, _asgetticket, _asrdresp \- routines for communicating with authentication servers
.SH SYNOPSIS
.nf
.PP
.ft L
#include <u.h>
#include <libc.h>
#include <authsrv.h>
.fi
.ta 8n +4n +4n +4n +4n +4n +4n
.PP
.B
int authdial(char *netroot, char *ad);
.PP
.B
int passtokey(char key[DESKEYLEN], char *password)
.PP
.B
uchar nvcsum(void *mem, int len)
.PP
.B
int readnvram(Nvrsafe *nv, int flag);
.PPP
.B
int convT2M(Ticket *t, char *msg, char *key)
.PP
.B
void convM2T(char *msg, Ticket *t, char *key)
.PP
.B
int convA2M(Authenticator *a, char *msg, char *key)
.PP
.B
void convM2A(char *msg, Authenticator *a, char *key)
.PP
.B
int convTR2M(Ticketreq *tr, char *msg)
.PP
.B
void convM2TR(char *msg, Ticketreq *tr)
.PP
.B
int convPR2M(Passwordreq *pr, char *msg, char *key)
.PP
.B
void convM2PR(char *msg, Passwordreq *pr, char *key)
.PP
.B
int _asgetticket(int fd, char *trbuf, char *tbuf);
.PP
.B
int _asrdresp(int fd, char *buf, int len);
.SH DESCRIPTION
.PP
.I Authdial
dials an authentication server over the
network rooted at
.IR net ,
default
.BR /net .
The authentication domain,
.IR ad ,
specifies which server to call.
If
.I ad
is non-nil,
the network database
(see
.IR ndb (1))
is queried for an entry which contains
.B authdom=\fIad\fP
or
.BR dom=\fIad\fP ,
the former having precedence,
and which also contains an
.B auth
attribute.
The string dialed is then
.I netroot\fP!\fIserver\fP!ticket
where
.I server
is the value of the
.B auth
attribute.
If no entry is found, the error string is
set to ``no authentication server found''
and -1 is returned.
If
.I authdom
is nil, the string
.IB netroot !$auth! ticket
is used to make the call.
.PP
.I Passtokey
converts
.I password
into a DES key and stores the result in
.IR key .
It returns 0 if
.I password
could not be converted,
and 1 otherwise.
.PP
.I Readnvram
reads authentication information into the structure:
.EX
.ta 4n +4n +8n +4n +4n +4n +4n
struct Nvrsafe
{
char machkey[DESKEYLEN];
uchar machsum;
char authkey[DESKEYLEN];
uchar authsum;
char config[CONFIGLEN];
uchar configsum;
char authid[ANAMELEN];
uchar authidsum;
char authdom[DOMLEN];
uchar authdomsum;
};
.EE
.PP
On Sparc, MIPS, and SGI machines this information is
in non-volatile ram, accessible in the file
.BR #r/nvram .
On x86s and Alphas
.I readnvram
successively opens the following areas stopping with the
first to succeed:
.PP
\- the partition named by the
.B $nvram
environment variable
(commonly set via
.IR plan9.ini (8))
.br
\- the partition
.B #S/sdC0/nvram
.br
\- a file called
.B plan9.nvr
in the partition
.B #S/sdC0/9fat
.br
\- the partition
.B #S/sd00/nvram
.br
\- a file called
.B plan9.nvr
in the partition
.B #S/sd00/9fat
.br
\- a file called
.B plan9.nvr
on a DOS floppy in drive 0
.br
\- a file called
.B plan9.nvr
on a DOS floppy in drive 1
.PP
The
.IR nvcsum s
of the fields
.BR machkey ,
.BR authid ,
and
.B authdom
must match their respective checksum or that field is zeroed.
If
.I flag
is
.B NVwrite
or at least one checksum fails and
.I flag
is
.BR NVwriteonerr ,
.I readnvram
will prompt for new values on
.B #c/cons
and then write them back to the storage area.
.PP
.IR ConvT2M ,
.IR convA2M ,
.IR convTR2M ,
and
.I convPR2M
convert tickets, authenticators, ticket requests, and password change request
structures into transmittable messages.
.IR ConvM2T ,
.IR convM2A ,
.IR convM2TR ,
and
.I convM2PR
are used to convert them back.
.I Key
is used for encrypting the message before transmission and decrypting
after reception.
.PP
The routine
.I _asgetresp
receives either a character array or an error string.
On error, it sets errstr and returns -1. If successful,
it returns the number of bytes received.
.PP
The routine
.I _asgetticket
sends a ticket request message and then uses
.I _asgetresp
to recieve an answer.
.SH SOURCE
.B \*9/src/libauthsrv
.SH SEE ALSO
.IR netkey (1),
.IR dial (3),
Plan 9's
\fIauthsrv\fR(6).
.SH DIAGNOSTICS
These routines set
.IR errstr .
Integer-valued functions return -1 on error.

87
man/man3/encrypt.3 Normal file
View file

@ -0,0 +1,87 @@
.TH ENCRYPT 2
.SH NAME
encrypt, decrypt, netcrypt \- DES encryption
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
int encrypt(void *key, void *data, int len)
.PP
.B
int decrypt(void *key, void *data, int len)
.PP
.B
int netcrypt(void *key, void *data)
.SH DESCRIPTION
.I Encrypt
and
.I decrypt
perform DES encryption and decryption.
.I Key
is an array of
.B DESKEYLEN
(defined as 7 in
.BR <auth.h> )
bytes containing the encryption key.
.I Data
is an array of
.I len
bytes;
it must be at least 8 bytes long.
The bytes are encrypted or decrypted in place.
.PP
The DES algorithm encrypts an individual 8-byte block of data.
.I Encrypt
uses the following method to encrypt data longer than 8 bytes.
The first 8 bytes are encrypted as usual.
The last byte of the encrypted result
is prefixed to the next 7 unencrypted bytes to make the next 8
bytes to encrypt.
This is repeated until fewer than 7 bytes remain unencrypted.
Any remaining unencrypted bytes are encrypted with enough of the preceding
encrypted bytes to make a full 8-byte block.
.I Decrypt
uses the inverse algorithm.
.PP
.I Netcrypt
performs the same encryption as a SecureNet Key.
.I Data
points to an
.SM ASCII
string of decimal digits with numeric value between 0 and 10000.
These digits are copied into an 8-byte buffer with trailing binary zero fill
and encrypted as one DES block.
The first four bytes are each formatted as two digit
.SM ASCII
hexadecimal numbers,
and the string is copied into
.IR data .
.SH SOURCE
.B /sys/src/libc/port
.SH DIAGNOSTICS
These routines return 1 if the data was encrypted,
and 0 if the encryption fails.
.I Encrypt
and
.I decrypt
fail if the data passed is less than 8 bytes long.
.I Netcrypt
can fail if it is passed invalid data.
.\" .SH SEE ALSO
.\" .IR securenet (8)
.SH BUGS
The implementation is broken in a way that makes
it unsuitable for anything but authentication.
.PP
To avoid name conflicts with the underlying system,
.IR encrypt
and
.IR decrypt
are preprocessor macros defined as
.IR p9encrypt
and
.IR p9decrypt ;
see
.IR intro (3).

476
man/man3/ndb.3 Normal file
View file

@ -0,0 +1,476 @@
.TH NDB 3
.SH NAME
ndbopen, ndbcat, ndbchanged, ndbclose, ndbreopen, ndbsearch, ndbsnext, ndbgetvalue, ndbfree, ipattr, ndbgetipaddr, ndbipinfo, ndbhash, ndbparse, ndbfindattr, ndbdiscard, ndbconcatenate, ndbreorder, ndbsubstitute, ndbgetval, ndblookval \- network database
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <bio.h>
.br
.B #include <ndb.h>
.ta \w'\fLNdbtuplexx 'u
.PP
.B
Ndb* ndbopen(char *file)
.PP
.B
Ndb* ndbcat(Ndb *db1, Ndb *db2)
.PP
.B
Ndb* ndbchanged(Ndb *db)
.PP
.B
int ndbreopen(Ndb *db)
.PP
.B
void ndbclose(Ndb *db)
.PP
.B
Ndbtuple* ndbsearch(Ndb *db, Ndbs *s, char *attr, char *val)
.PP
.B
Ndbtuple* ndbsnext(Ndbs *s, char *attr, char *val)
.PP
.B
char* ndbgetvalue(Ndb *db, Ndbs *s, char *attr, char *val,
.br
.B
char *rattr, Ndbtuple **tp)
.\" .PP
.\" .B
.\" char* csgetvalue(char *netroot, char *attr, char *val, char *rattr,
.\" Ndbtuple **tp)
.PP
.B
char* ipattr(char *name)
.PP
.B
Ndbtuple* ndbgetipaddr(Ndb *db, char *sys);
.PP
.B
Ndbtuple* ndbipinfo(Ndb *db, char *attr, char *val, char **attrs,
.br
.B int nattr)
.\" .PP
.\" .B
.\" Ndbtuple* csipinfo(char *netroot, char *attr, char *val, char **attrs,
.\" .br
.\" .B int nattr)
.PP
.B
ulong ndbhash(char *val, int hlen)
.PP
.B
Ndbtuple* ndbparse(Ndb *db)
.\" .PP
.\" .B
.\" Ndbtuple* dnsquery(char *netroot, char *domainname, char *type)
.PP
.B
Ndbtuple* ndbfindattr(Ndbtuple *entry, Ndbtuple *line, char *attr)
.PP
.B
void ndbfree(Ndbtuple *db)
.PP
.B
Ndbtuple* ndbdiscard(Ndbtuple *t, Ndbtuple *a)
.PP
.B
Ndbtuple* ndbconcatenate(Ndbtuple *a, Ndbtuple *b);
.PP
.B
Ndbtuple* ndbreorder(Ndbtuple *t, Ndbtuple *a);
.PP
.B
Ndbtuple* ndbsubstitute(Ndbtuple *t, Ndbtuple *from, Ndbtuple *to);
.SH DESCRIPTION
These routines are used by network administrative programs to search
the network database.
They operate on the database files described in
.IR ndb (6).
.PP
.I Ndbopen
opens the database
.I file
and calls
.IR malloc (2)
to allocate a buffer for it.
If
.I file
is zero, all network database files are opened.
.PP
.I Ndbcat
concatenates two open databases. Either argument may be
nil.
.PP
.I Ndbreopen
checks if the database files associated with
.I db
have changed and if so throws out any cached information and reopens
the files.
.PP
.I Ndbclose
closes any database files associated with
.I db
and frees all storage associated with them.
.PP
.I Ndbsearch
and
.I ndbsnext
search a database for an entry containing the
attribute/value pair,
.IR attr = val .
.I Ndbsearch
is used to find the first match and
.I ndbsnext
is used to find each successive match.
On a successful search both return a linked list of
.I Ndbtuple
structures acquired by
.IR malloc (2)
that represent the attribute/value pairs in the
entry.
On failure they return zero.
.IP
.EX
typedef struct Ndbtuple Ndbtuple;
struct Ndbtuple {
char attr[Ndbalen];
char *val;
Ndbtuple *entry;
Ndbtuple *line;
ulong ptr; /* for the application; starts 0 */
char valbuf[Ndbvlen]; /* initial allocation for val */
};
.EE
.LP
The
.I entry
pointers chain together all pairs in the entry in a null-terminated list.
The
.I line
pointers chain together all pairs on the same line
in a circular list.
Thus, a program can implement 2 levels of binding for
pairs in an entry.
In general, pairs on the same line are bound tighter
than pairs on different lines.
.PP
The argument
.I s
of
.I ndbsearch
has type
.I Ndbs
and should be pointed to valid storage before calling
.IR ndbsearch ,
which will fill it with information used by
.I ndbsnext
to link successive searches.
The structure
.I Ndbs
looks like:
.IP
.EX
typedef struct Ndbs Ndbs;
struct Ndbs {
Ndb *db; /* data base file being searched */
...
Ndbtuple *t; /* last attribute value pair found */
};
.EE
.LP
The
.I t
field points to the pair within the entry matched by the
.I ndbsearch
or
.IR ndbsnext .
.PP
.I Ndbgetvalue
searches the database for an entry containing not only an
attribute/value pair,
.IR attr = val ,
but also a pair with the attribute
.IR rattr .
If successful, it returns a malloced copy of the null terminated value associated with
.IR rattr .
If
.I tp
is non nil,
.I *tp
will point to the entry. Otherwise the entry will be freeed.
.\" .PP
.\" .I Csgetvalue
.\" is like
.\" .I ndbgetvalue
.\" but queries the connection server
.\" instead of looking directly at the database.
.\" Its first argument specifies the network root to use.
.\" If the argument is 0, it defaults to
.\" \f5"/net"\f1.
.PP
.I Ndbfree
frees a list of tuples returned by one of the other
routines.
.PP
.I Ipattr
takes the name of an IP system and returns the attribute
it corresponds to:
.RS
.TP
.B dom
domain name
.TP
.B ip
Internet number
.TP
.B sys
system name
.RE
.PP
.I Ndbgetipaddr
looks in
.I db
for an entry matching
.I sys
as the value of a
.B sys=
or
.B dom=
attribute/value pair and returns all IP addresses in the entry.
If
.I sys
is already an IP address, a tuple containing just
that address is returned.
.PP
.I Ndbipinfo
looks up Internet protocol information about a system.
This is an IP aware search. It looks first for information
in the system's database entry and then in the database entries
for any IP subnets or networks containing the system.
The system is identified by the
attribute/value pair,
.IR attr = val .
.I Ndbipinfo
returns a list of tuples whose attributes match the
attributes in the
.I n
element array
.IR attrs .
For example, consider the following database entries describing a network,
a subnetwork, and a system.
.PP
.EX
ipnet=big ip=10.0.0.0
dns=dns.big.com
smtp=smtp.big.com
ipnet=dept ip=10.1.1.0 ipmask=255.255.255.0
smtp=smtp1.big.com
ip=10.1.1.4 dom=x.big.com
bootf=/386/9pc
.EE
.PP
Calling
.PP
.EX
ndbipinfo(db, "dom", "x.big.com", ["bootf" "smtp" "dns"], 3)
.EE
.PP
will return the tuples
.BR bootf=/386/9pc ,
.BR smtp=smtp1.big.com ,
and
.BR dns=dns.big.com .
.\" .PP
.\" .I Csipinfo
.\" is to
.\" .I ndbipinfo
.\" as
.\" .I csgetval
.\" is to
.\" .IR ndbgetval .
.PP
The next three routines are used by programs that create the
hash tables and database files.
.I Ndbhash
computes a hash offset into a table of length
.I hlen
for the string
.IR val .
.I Ndbparse
reads and parses the next entry from the database file.
Multiple calls to
.IR ndbparse
parse sequential entries in the database file.
A zero is returned at end of file.
.\" .PP
.\" .I Dnsquery
.\" submits a query about
.\" .I domainname
.\" to the
.\" .I ndb/dns
.\" mounted at
.\" .IB netroot /dns.
.\" It returns a linked list of
.\" .I Ndbtuple's
.\" representing a single database entry.
.\" The tuples are logicly arranged into lines using the
.\" .B line
.\" fieldin the structure.
.\" The possible
.\" .IR type 's
.\" of query are and the attributes on each returned tuple line is:
.\" .TP
.\" .B ip
.\" find the IP addresses. Returns
.\" domain name
.\" .RI ( dom )
.\" and ip address
.\" .RI ( ip )
.\" .TP
.\" .B mx
.\" look up the mail exchangers. Returns preference
.\" .RI ( pref )
.\" and exchanger
.\" .RI ( mx )
.\" .TP
.\" .B ptr
.\" do a reverse query. Here
.\" .I domainname
.\" must be an
.\" .SM ASCII
.\" IP address. Returns reverse name
.\" .RI ( ptr )
.\" and domain name
.\" .RI ( dom )
.\" .TP
.\" .B cname
.\" get the system that this name is a nickname for. Returns the nickname
.\" .RI ( dom )
.\" and the real name
.\" .RI ( cname )
.\" .TP
.\" .B soa
.\" return the start of area record for this field. Returns
.\" area name
.\" .RI ( dom ),
.\" primary name server
.\" .RI ( ns ),
.\" serial number
.\" .RI ( serial ),
.\" refresh time in seconds
.\" .RI ( refresh ),
.\" retry time in seconds
.\" .RI ( retry ),
.\" expiration time in seconds
.\" .RI ( expire ),
.\" and minimum time to lie
.\" .RI ( ttl ).
.\" .TP
.\" .B ns
.\" name servers. Returns domain name
.\" .RI ( dom )
.\" and name server
.\" .RI ( ns )
.PP
.I Ndbfindattr
searches
.I entry
for the tuple
with attribute
.I attr
and returns a pointer to the tuple.
If
.I line
points to a particular line in the entry, the
search starts there and then wraps around to the beginning
of the entry.
.PP
All of the routines provided to search the database
provide an always consistent view of the relevant
files. However, it may be advantageous for an application
to read in the whole database using
.I ndbopen
and
.I ndbparse
and provide its own search routines. The
.I ndbchanged
routine can be used by the application to periodicly
check for changes. It returns zero
if none of the files comprising the database have
changes and non-zero if they have.
.PP
Finally, a number of routines are provided for manipulating
tuples.
.PP
.I Ndbdiscard
removes attr/val pair
.I a
from tuple
.I t
and frees it.
If
.I a
isn't in
.I t
it is just freed.
.PP
.I Ndbconcatenate
concatenates two tuples and returns the result. Either
or both tuples may be nil.
.PP
.I Ndbreorder
reorders a tuple
.IR t
to make the line containing attr/val pair
.I a
first in the entry and making
.I a
first in its line.
.PP
.I Ndbsubstitute
replaces a single att/val pair
.I from
in
.I t
with the tuple
.IR to .
All attr/val pairs in
.I to
end up on the same line.
.I from
is freed.
.SH FILES
.TP
.B \*9/ndb
directory of network database files
.PD
.SH SOURCE
.B \*9/src/libndb
.SH SEE ALSO
.IR ndb (1)
.IR ndb (7)
.SH DIAGNOSTICS
.IR Ndbgetvalue
and
.I ndblookvalue
set
.I errstr
to
.B "buffer too short"
if the buffer provided isn't long enough for the
returned value.
.SH BUGS
.IR Ndbgetval
and
.I ndblookval
are deprecated versions of
.IR ndbgetvalue
and
.IR ndblookvalue .
They expect a fixed 64 byte long result
buffer and existed when the values of a
.I Ndbtuple
structure where fixed length.

18
man/man3/open.3
View file

@ -38,9 +38,12 @@ says to close the file when an
or
.I execl
system call is made;
and
.B ORCLOSE
says to remove the file when it is closed (by everyone who has a copy of the file descriptor).
says to remove the file when it is closed (by everyone who has a copy of the file descriptor);
and
.B OAPPEND
says to open the file in append-only mode, so that writes
are always appended to the end of the file.
.I Open
fails if the file does not exist or the user does not have
permission to open it for the requested purpose
@ -145,3 +148,14 @@ allows the file descriptor to be reused.
.SH DIAGNOSTICS
These functions set
.IR errstr .
.SH BUGS
Not all functionality is supported on all systems.
.PP
The
.B DMAPPEND
bit is not supported on any systems.
.PP
The implementation of
.B ORCLOSE
is to unlink the file after opening it, causing problems
in programs that try to access the file by name before it is closed.

48
man/man3/readcons.3 Normal file
View file

@ -0,0 +1,48 @@
.TH READCONS 3
.SH NAME
readcons \- prompt console for input
.SH SYNOPSIS
.B
#include <u.h>
.PP
.B
#include <libc.h>
.PP
.B
char *readcons(char *prompt, char *def, int secret)
.SH DESCRIPTION
.I Readcons
prompts at the console for input.
It returns a NUL-terminated buffer containing the input
without a final newline.
The buffer should be freed (and perhaps cleared first)
when no longer needed.
.PP
If the user types an empty string (just a newline) and
.I def
is non-zero, then a copy of
.I def
is returned instead of the empty string.
.PP
If
.I secret
is non-zero, the input is not echoed to the screen.
.SH EXAMPLE
A stripped-down version of
.IR netkey (1):
.IP
.EX
pass = readcons("password", nil, 1);
passtokey(key, pass);
memset(pass, 0, strlen(pass));
free(pass);
for(;;){
chal = readcons("challenge", nil, 0);
sprint(buf, "%d", strtol(chal, 0, 10));
free(chal);
netcrypt(key, buf);
print("response: %s\n", buf);
}
.EE
.SH SOURCE
.B \*9/src/lib9/readcons.c

29
man/man3/sysfatal.3
View file

@ -1,12 +1,15 @@
.TH SYSFATAL 3
.SH NAME
sysfatal \- system error messages
syslog, sysfatal \- system error messages
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.PP
.B
void syslog(int cons, char *logname, char *fmt, ...)
.PP
.B
void sysfatal(char *fmt, ...)
.SH DESCRIPTION
.I Sysfatal
@ -28,6 +31,30 @@ interface to process its arguments.
If
.B argv0
is null, it is ignored and the following colon and space are suppressed.
.PP
.I Syslog
logs messages in the file named by
.I logname
in the directory
.B \*9/log ;
the file must already exist and is opened append-only.
.I Logname
must contain no slashes.
The message is a line with several fields:
the name of the machine writing the message;
the date and time;
the message specified by the
.IR print (2)
format
.I fmt
and any following arguments;
and a final newline.
If
.I cons
is set or the log file cannot be opened, the message is also printed
on the system console.
.I Syslog
can be used safely in multi-threaded programs.
.SH SOURCE
.B \*9/src/lib9/sysfatal.c
.SH "SEE ALSO"

705
man/man4/factotum.4 Normal file
View file

@ -0,0 +1,705 @@
.TH FACTOTUM 4
.SH NAME
factotum \- authentication agent
.SH SYNOPSIS
.B factotum
[
.B -DdkSun
] [
.B -a authaddr
] [
.B -s
.I srvname
]
.\" [
.\" .B -m
.\" .I mtpt
.\" ]
.PP
.B factotum
.B -g
.IB attribute = value
.B ...
.IB attribute ?
.B ...
.\" .PP
.\" .B auth/fgui
.SH DESCRIPTION
.I Factotum
is a user-level file system that
acts as the authentication agent for a user.
It does so by managing a set of
.IR keys .
A key is a collection of information used to authenticate a particular action.
Stored as a list of
.IB attribute = value
pairs, a key typically contains a user, an authentication domain, a protocol, and
some secret data.
.PP
.I Factotum
presents the following files:
.TF needkey
.TP
.B rpc
each open represents a new private channel to
.I factotum
.TP
.B proto
when read lists the protocols available
.TP
.B confirm
for confiming the use of key
.TP
.B needkey
allows external programs to control the addition of new keys
.TP
.B log
a log of actions
.TP
.B ctl
for maintaining keys; when read, it returns a list of keys.
For secret attributes, only the attribute name follow by a
.L ?
is returned.
.PD
.PP
In any authentication, the caller typically acts as a client
and the callee as a server. The server determines
the authentication domain, sometimes after a negotiation with
the client. Authentication always requires the client to
prove its identity to the server. Under some protocols, the
authentication is mutual.
Proof is accomplished using secret information kept by factotum
in conjunction with a cryptographic protocol.
.PP
.I Factotum
can act in the role of client for any process possessing the
same user id as it. For select protocols such as
.B p9sk1
it can also act as a client for other processes provided
its user id may speak for the other process' user id (see
Plan 9's
\fIauthsrv\fR(6)).
.I Factotum
can act in the role of server for any process.
.PP
.IR Factotum 's
structure is independent of
any particular authentication protocol.
.I Factotum
supports the following protocols:
.TF mschap
.TP
.B p9any
a metaprotocol used to negotiate which actual protocol to use.
.TP
.B p9sk1
a Plan 9 shared key protocol.
.TP
.B p9sk2
a variant of
.B p9sk1.
.TP
.B p9cr
a Plan 9 protocol that can use either
.B p9sk1
keys or SecureID tokens.
.TP
.B apop
the challenge/response protocol used by POP3 mail servers.
.TP
.B cram
the challenge/response protocol also used by POP3 mail servers.
.TP
.B chap
the challenge/response protocols used by PPP and PPTP.
.TP
.B mschap
a proprietary Microsoft protocol also used by PPP and PPTP.
.TP
.B rsa
RSA public key decryption, used by SSH and TLS.
.TP
.B pass
passwords in the clear.
.TP
.B vnc
.IR vnc (1)'s
challenge/response.
.TP
.B wep
WEP passwords for wireless ethernet cards.
.PD
.PP
The options are:
.TP
.B \-a
supplies the address of the authentication server to use.
Without this option, it will attempt to find an authentication server by
querying the connection server, the file
.BR <mtpt>/ndb ,
and finally the network database in
.BR /lib/ndb .
.TP
.B \-m
specifies the mount point to use, by default
.BR /mnt .
.TP
.B \-s
specifies the service name to use.
Without this option,
.I factotum
does not create a service file in
.BR /srv .
.TP
.B \-D
turns on 9P tracing, written to standard error.
.TP
.B \-d
turns on debugging, written to standard error.
.TP
.B \-g
causes the agent to prompt for the key, write it
to the
.B ctl
file, and exit.
The agent will prompt for values for any of the
attributes ending with a question mark
.RB ( ? )
and will append all the supplied
.I attribute = value
pairs. See the section on key templates below.
.TP
.B \-n
don't look for a secstore.
.TP
.B \-S
indicates that the agent is running on a
cpu server. On starting, it will attempt to get a
.B 9psk1
key from NVRAM using
.B readnvram
(see
.IR authsrv (3)),
prompting for anything it needs.
It will never subsequently prompt for a
key that it doesn't have.
This option is typically used by
the kernel at boot time.
.TP
.B \-k
causes the NVRAM to be written.
It is only valid with the
.B \-S
option.
This option is typically used by
the kernel at boot time.
.TP
.B \-u
causes the agent to prompt for user
id and writes it to
.BR /dev/hostowner .
It is mutually exclusive with
.B \-k
and
.BR \-S .
This option is typically used by
the kernel at boot time.
.PD
.\" .PP
.\" .I Fgui
.\" is a graphic user interface for confirming key usage and
.\" entering new keys. It hides the window in which it starts
.\" and waits reading requests from
.\" .B confirm
.\" and
.\" .BR needkey .
.\" For each requests, it unhides itself and waits for
.\" user input.
.\" See the sections on key confirmation and key prompting below.
.SS "Key Tuples
.PP
A
.I "key tuple
is a space delimited list of
.IB attribute = value
pairs. An attribute whose name begins with an exclamation point
.RB ( ! )
does not appear when reading the
.B ctl
file.
The required attributes depend on the authentication protocol.
.PP
.BR P9sk1 ,
.BR p9sk2 ,
and
.BR p9cr
all require a key with
.BR proto = p9sk1 ,
a
.B dom
attribute identifying the authentication domain, a
.B user
name valid in that domain, and either a
.B !password
or
.B !hex
attribute specifying the password or hexadecimal secret
to be used. Here is an example:
.PP
.EX
proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
.EE
.PP
.BR Apop ,
.BR cram ,
.BR chap ,
and
.BR mschap ,
require a key with a
.B proto
attribute whose value matches the protocol,
in addition to
.BR server ,
.BR user ,
and
.B !password
attributes;
e.g.
.PP
.EX
proto=apop server=mit.edu user=rsc !password=nerdsRus
.EE
Vnc is similar but does not require a
.B user
attribute.
.PP
.B Pass
requires a key with
.B proto=pass
in addition to
.B user
and
.B !password
attributes; e.g.
.PP
.EX
proto=pass user=tb !password=does.it.matter
.EE
.PP
.B Rsa
requires a key with
.B proto=rsa
in addition to all the hex attributes defining an RSA key:
.BR ek ,
.BR n ,
.BR !p ,
.BR !q ,
.BR !kp ,
.BR !kq ,
.BR !c2 ,
and
.BR !dk .
By convention, programs using the RSA protocol also require a
.B service
attribute set to
.BR ssh ,
.BR sshserve ,
or
.BR tls .
.PP
.B Wep
requires a
.BR key1 ,
.BR key2 ,
or
.BR key3
set to the password to be used.
Starting the protocol causes
.I factotum
to configure the wireless ethernet card
.B #l/ether0
for WEP encryption with the given password.
.PP
All keys can have additional attibutes that act either as comments
or as selectors to distinguish them in the
.IR auth (2)
library calls.
.PP
The factotum owner can use any key stored by factotum.
Any key may have one or more
.B owner
attributes listing the users who can use the key
as though they were the owner.
For example, the TLS and SSH host keys on a server
often have an attribute
.B owner=*
to allow any user (and in particular,
.L none )
to run the TLS or SSH server-side protocol.
.PP
Any key may have a
.B role
attribute for restricting how it can be used.
If this attribute is missing, the key can be used in any role.
The possible values are:
.TP
.B client
for authenticating outbound calls
.TP
.B server
for authenticating inbound calls
.TP
.B speaksfor
for authenticating processes whose
user id does not match
.IR factotum 's.
.PD
.PP
Whenever
.I factotum
runs as a server, it must have a
.B p9sk1
key in order to communicate with the authentication
server for validating passwords and challenge/responses of
other users.
.SS "Key Templates
Key templates are used by routines that interface to
.I factotum
such as
.B auth_proxy
and
.B auth_challenge
(see
.IR auth (3))
to specify which key and protocol to use for an authentication.
Like a key tuple, a key template is also a list of
.IB attribute = value
pairs.
It must specify at least the protocol and enough
other attributes to uniquely identify a key, or set of keys, to use.
The keys chosen are those that match all the attributes specified
in the template. The possible attribute/value formats are:
.TP 1i
.IB attr = val
The attribute
.I attr
must exist in the key and its value must exactly
match
.I val
.TP 1i
.IB attr ?
The attribute
.I attr
must exist in the key but its value doesn't matter.
.TP 1i
.I attr
The attribute
.I attr
must exist in the key with a null value
.PD
.PP
Key templates are also used by factotum to request a key either via
an RPC error or via the
.B needkey
interface.
The possible attribute/value formats are:
.TP 1i
.IB attr = val
This pair must remain unchanged
.TP 1i
.IB attr ?
This attribute needs a value
.TP 1i
.I attr
The pair must remain unchanged
.PD
.SS "Control and Key Management
.PP
A number of messages can be written to the control file.
The mesages are:
.TP
.B "key \fIattribute-value-list\fP
add a new key. This will replace any old key whose
public, i.e. non ! attributes, match.
.TP
.B "delkey \fIattribute-value-list\fP
delete a key whose attributes match those given.
.TP
.B debug
toggle debugging on and off, i.e., the debugging also
turned on by the
.B \-d
option.
.PP
By default when factotum starts it looks for a
.IR secstore (1)
account on $auth for the user and, if one exists,
prompts for a secstore password in order to fetch
the file
.IR factotum ,
which should contain control file commands.
An example would be
.EX
key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
key proto=rsa service=ssh size=1024 ek=3B !dk=...
.EE
where the first line sets a password for
challenge/response authentication, strong against dictionary
attack by being a long random string, and the second line
sets a public/private keypair for ssh authentication,
generated by
.B ssh_genkey
(see
.IR ssh (1)).
.PD
.SS "Confirming key use
.PP
The
.B confirm
file provides a connection from
.I factotum
to a confirmation server, normally the program
.IR auth/fgui .
Whenever a key with the
.B confirm
attribute is used,
.I factotum
requires confirmation of its use. If no process has
.B confirm
opened, use of the key will be denied.
However, if the file is opened a request can be read from it
with the following format:
.PP
.B confirm
.BI tag= tagno
.I "<key template>
.PP
The reply, written back to
.BR confirm ,
consists of string:
.PP
.BI tag= tagno
.BI answer= xxx
.PP
If
.I xxx
is the string
.B yes
then the use is confirmed and the authentication will proceed.
Otherwise, it fails.
.PP
.B Confirm
is exclusive open and can only be opened by a process with
the same user id as
.IR factotum .
.SS "Prompting for keys
.PP
The
.B needkey
file provides a connection from
.I factotum
to a key server, normally the program
.IR auth/fgui .
Whenever
.I factotum
needs a new key, it first checks to see if
.B needkey
is opened. If it isn't, it returns a error to its client.
If the file is opened a request can be read from it
with the following format:
.PP
.B needkey
.BI tag= tagno
.I "<key template>
.PP
It is up to the reader to then query the user for any missing fields,
write the key tuple into the
.B ctl
file, and then reply by writing into the
.B needkey
file the string:
.PP
.BI tag= tagno
.PP
.B Needkey
is exclusive open and can only be opened by a process with
the same user id as
.IR factotum .
.SS "The RPC Protocol
Authentication is performed by
.IP 1)
opening
.BR rpc
.IP 2)
setting up the protocol and key to be used (see the
.B start
RPC below),
.IP 3)
shuttling messages back and forth between
.IR factotum
and the other party (see the
.B read
and
.B write
RPC's) until done
.IP 4)
if successful, reading back an
.I AuthInfo
structure (see
.IR authsrv (3)).
.PP
The RPC protocol is normally embodied by one of the
routines in
.IR auth (3).
We describe it here should anyone want to extend
the library.
.PP
An RPC consists of writing a request message to
.B rpc
followed by reading a reply message back.
RPC's are strictly ordered; requests and replies of
different RPC's cannot be interleaved.
Messages consist of a verb, a single space, and data.
The data format depends on the verb. The request verbs are:
.TP
.B "start \fIattribute-value-list\fP
start a new authentication.
.I Attribute-value-pair-list
must include a
.B proto
attribute, a
.B role
attribute with value
.B client
or
.BR server ,
and enough other attibutes to uniquely identify a key to use.
A
.B start
RPC is required before any others. The possible replies are:
.RS
.TP
.B ok
start succeeded.
.TP
.B "error \fIstring\fP
where
.I string
is the reason.
.RE
.PD
.TP
.B read
get data from
.I factotum
to send to the other party. The possible replies are:
.RS
.TP
.B ok
read succeeded, this is zero length message.
.TP
.B "ok \fIdata\fP
read succeeded, the data follows the space and is
unformatted.
.TP
.B "done
authentication has succeeded, no further RPC's are
necessary
.TP
.B "done haveai
authentication has succeeded, an
.B AuthInfo
structure (see
.IR auth (3))
can be retrieved with an
.B authinfo
RPC
.TP
.B "phase \fIstring\fP
its not your turn to read, get some data from
the other party and return it with a write RPC.
.TP
.B "error \fIstring\fP
authentication failed,
.I string
is the reason.
.TP
.B "protocol not started
a
.B start
RPC needs to precede reads and writes
.TP
.B "needkey \fIattribute-value-list\fP
a key matching the argument is needed. This argument
may be passed as an argument to
.I factotum
.B -g
in order to prompt for a key. After that, the
authentication may proceed, i.e., the read restarted.
.PD
.RE
.TP
.B "write \fIdata\fP
send data from the other party to
.IR factotum .
The possible replies are:
.RS
.TP
.B "ok
the write succeeded
.TP
.B "needkey \fIattribute-value-list\fP
see above
.TP
.B "toosmall \fIn\fP
the write is too short, get more data from the
other party and retry the write.
.I n
specifies the maximun total number of bytes.
.TP
.B "phase \fIstring\fP
its not your turn to write, get some data from
.I factotum
first.
.TP
.B "done
see above
.TP
.B "done haveai
see above
.RE
.TP
.B authinfo
retrieve the AuthInfo structure.
The possible replies are:
.RS
.TP
.B "ok \fIdata\fP
.I data
is a marshaled form of the AuthInfo structure.
.TP
.B "error \fIstring\fP
where
.I string
is the reason for the error.
.PD
.RE
.TP
.B attr
retrieve the attributes used in the
.B start
RPC.
The possible replies are:
.RS
.TP
.B "ok \fIattribute-value-list\fP
.TP
.B "error \fIstring\fP
where
.I string
is the reason for the error.
.PD
.RE
.SH SOURCE
.B \*9/src/cmd/factotum

306
man/man7/ndb.7 Normal file
View file

@ -0,0 +1,306 @@
.TH NDB 7
.SH NAME
ndb \- Network database
.SH DESCRIPTION
.PP
The network database consists of files
describing machines known to the local
installation and machines known publicly.
The files comprise multi-line tuples made up of
attribute/value pairs of the form
.IB attr = value
or sometimes just
.IR attr .
Each line starting without white space starts a new tuple.
Lines starting with
.B #
are comments.
.PP
The file
.B /lib/ndb/local
is the root of the database.
Other files are included in the
database if a tuple with an
attribute-value pair of attribute
.B database
and no value exists in
.BR /lib/ndb/local .
Within the
.B database
tuple,
each pair with attribute
.B file
identifies a file to be included in the database. The files are searched
in the order they appear.
For example:
.IP
.EX
database=
file=/lib/ndb/common
file=/lib/ndb/local
file=/lib/ndb/global
.EE
.PP
declares the database to be composed of the three files
.BR /lib/ndb/common ,
.BR /lib/ndb/local ,
and
.BR /lib/ndb/global .
By default,
.B /lib/ndb/local
is searched before the others.
However,
.B /lib/ndb/local
may be included in the
.B database
to redefine its ordering.
.PP
Within tuples, pairs on the same line bind tighter than
pairs on different lines.
.PP
Programs search the database directly using the routines in
.IR ndb (2).
.\" or indirectly using
.\" .B ndb/cs
.\" and
.\" .B ndb/dns
.\" (see
.\" .IR ndb (1)).
.\" Both
.\" .B ndb/cs
The routine
.I ndbipinfo
imposes structure on the otherwise flat database by using
knowledge specific to the network.
The internet is made up of networks which can be subnetted
multiple times. A network must have an
.B ipnet
attribute and is uniquely identified by the values of its
.B ip
and
.B ipmask
attributes. If the
.B ipmask
is missing, the relevant Class A, B or C one is used.
.LP
A search for an attribute associated with a network or host starts
at the lowest level, the entry for the host or network itself,
and works its way up, bit by bit, looking at entries for nets/subnets
that include the network or host. The search ends when the attribute
is found.
For example, consider at the following entries:
.IP
.EX
ipnet=murray-hill ip=135.104.0.0 ipmask=255.255.0.0
dns=135.104.10.1
ntp=ntp.cs.bell-labs.com
ipnet=plan9 ip=135.104.9.0 ipmask=255.255.255.0
ntp=oncore.cs.bell-labs.com
smtp=smtp1.cs.bell-labs.com
ip=135.104.9.6 sys=anna dom=anna.cs.bell-labs.com
smtp=smtp2.cs.bell-labs.com
.EE
.LP
Here
.B anna
is on the subnet
.B plan9
which is in turn on the class B net
.BR murray-hill .
Assume that we're searching for
.BR anna 's
.B NTP
and
.B SMTP
servers.
The search starts by looking for an entry with
.BR sys=anna .
We find the anna entry. Since it has an
.B smtp=smtp2.cs.bell-labs.com
pair,
we're done looking for that attribute.
To fulfill the NTP request, we continue by looking for networks
that include anna's IP address.
We lop off the right most one bit from anna's address and
look for an
.B ipnet=
entry with
.BR ip=135.104.9.4 .
Not finding one, we drop another bit and look for an
.B ipnet=
entry with
.BR ip=135.104.9.0 .
There is
such an entry and it has the pair,
.BR ntp=oncore.cs.bell-labs.com ,
ending our search.
.\" .PP
.\" .I Ndb/cs
.\" can be made to perform such network aware
.\" searches by using metanames in the dialstring.
.\" A metaname is a
.\" .I $
.\" followed by an attribute name.
.\" .I Ndb/cs
.\" looks up the attribute relative to the system it is running
.\" on. Thus, with the above example, if a program called
.\" .IP
.\" .EX
.\" dial("tcp!$smtp!smtp", 0, 0, 0);
.\" .EE
.\" .LP
.\" the dial would connect to the SMTP port of
.\" .BR smtp2.cs.bell-labs.com .
.PP
A number of attributes are meaningful to programs and thus
reserved.
They are:
.TF restricted
.TP
.B sys
system name
.TP
.B dom
Internet domain name
.TP
.B ip
Internet address
.TP
.B ether
Ethernet address
.TP
.B bootf
file to download for initial bootstrap
.TP
.B ipnet
Internet network name
.TP
.B ipmask
Internet network mask
.TP
.B ipgw
Internet gateway
.TP
.B auth
authentication server to be used
.TP
.B authdom
authentication domain. Plan 9 supports multiple authentication
domains. To specify an authentication server for a particular domain,
add a tuple containing both
.B auth
and
.B authdom
attributes and values.
.TP
.B fs
file server to be used
.TP
.B tcp
a TCP service name
.TP
.B udp
a UDP service name
.TP
.B il
an IL service name
.TP
.B port
a TCP, UDP, or IL port number
.TP
.B restricted
a TCP service that can be called only by ports numbered
less that 1024
.TP
.B proto
a protocol supported by a host.
The pair
.B proto=il
is needed by
.I cs
(see
.IR ndb (8))
in tuples for hosts that support the IL protocol
.TP
.B dnsdomain
a domain name that
.I ndb/dns
adds onto any unrooted names when doing a search
There may be multiple
.B dnsdomain
pairs.
.TP
.B dns
a DNS server to use (for DNS and DHCP)
.TP
.B ntp
an NTP server to use (for DHCP)
.TP
.B smtp
an SMTP server to use (for DHCP)
.TP
.B time
a time server to use (for DHCP)
.TP
.B wins
a Windows name server (for DHCP)
.TP
.B mx
mail exchanger (for DNS and DHCP)
.TP
.B soa
start of area (for DNS)
.sp
.PD
.\" .PP
.\" The file
.\" .B \*9/ndb/auth
.\" is used during authentication to decide who has the power to `speak for' other
.\" users; see
.\" .IR authsrv (6).
.SH EXAMPLES
.LP
A tuple for the CPU server, spindle.
.LP
.EX
sys = spindle
dom=spindle.research.bell-labs.com
bootf=/mips/9powerboot
ip=135.104.117.32 ether=080069020677
proto=il
.EE
.LP
Entries for the network
.B mh-astro-net
and its subnets.
.LP
.EX
ipnet=mh-astro-net ip=135.104.0.0 ipmask=255.255.255.0
fs=bootes.research.bell-labs.com
ipgw=r70.research.bell-labs.com
auth=p9auth.research.bell-labs.com
ipnet=unix-room ip=135.104.117.0
ipgw=135.104.117.1
ipnet=third-floor ip=135.104.51.0
ipgw=135.104.51.1
.EE
.LP
Mappings between TCP service names and port numbers.
.LP
.EX
.ta \w'\fLtcp=sysmonxxxxx'u \w'\fLtcp=sysmonxxxxxport=512xxx'u
tcp=sysmon port=401
tcp=rexec port=512 restricted
tcp=9fs port=564
.EE
.SH FILES
.TP
.B \*9/ndb/local
first database file searched
.SH "SEE ALSO"
.\" .IR dial (2),
.IR ndb (1),
.IR ndb (3)
.\" .IR dhcpd (8),
.\" .IR ipconfig (8),
.\" .IR con (1)