diff options
Diffstat (limited to 'man/4')
| -rw-r--r-- | man/4/0intro | 16 | ||||
| -rw-r--r-- | man/4/9srvfs | 73 | ||||
| -rw-r--r-- | man/4/INDEX | 30 | ||||
| -rw-r--r-- | man/4/acme | 406 | ||||
| -rw-r--r-- | man/4/archfs | 64 | ||||
| -rw-r--r-- | man/4/cpu | 141 | ||||
| -rw-r--r-- | man/4/dbfs | 127 | ||||
| -rw-r--r-- | man/4/dossrv | 76 | ||||
| -rw-r--r-- | man/4/export | 69 | ||||
| -rw-r--r-- | man/4/factotum | 717 | ||||
| -rw-r--r-- | man/4/ftpfs | 117 | ||||
| -rw-r--r-- | man/4/import | 148 | ||||
| -rw-r--r-- | man/4/iostats | 81 | ||||
| -rw-r--r-- | man/4/keyfs | 116 | ||||
| -rw-r--r-- | man/4/keysrv | 116 | ||||
| -rw-r--r-- | man/4/kfs | 175 | ||||
| -rw-r--r-- | man/4/lockfs | 89 | ||||
| -rw-r--r-- | man/4/logfile | 45 | ||||
| -rw-r--r-- | man/4/memfs | 62 | ||||
| -rw-r--r-- | man/4/mntgen | 30 | ||||
| -rw-r--r-- | man/4/namespace | 332 | ||||
| -rw-r--r-- | man/4/palmsrv | 49 | ||||
| -rw-r--r-- | man/4/ramfile | 63 | ||||
| -rw-r--r-- | man/4/registry | 196 | ||||
| -rw-r--r-- | man/4/spree | 195 | ||||
| -rw-r--r-- | man/4/tarfs | 40 |
26 files changed, 3573 insertions, 0 deletions
diff --git a/man/4/0intro b/man/4/0intro new file mode 100644 index 00000000..f7d28560 --- /dev/null +++ b/man/4/0intro @@ -0,0 +1,16 @@ +.TH INTRO 4 +.SH NAME +intro \- introduction to file servers +.SH DESCRIPTION +This section describes programs that serve Styx +(see +.IR intro (5)), +and can therefore +be mounted, generating a new part of the name space. +Some, such as +.IR dossrv , +thereby make the contents of a foreign file format visible directly +to Inferno applications; +others, such as +.IR acme , +provide their own services through operations on files in a name space. diff --git a/man/4/9srvfs b/man/4/9srvfs new file mode 100644 index 00000000..19089931 --- /dev/null +++ b/man/4/9srvfs @@ -0,0 +1,73 @@ +.TH 9SRVFS 4 "Plan 9" +.SH NAME +9srvfs \- add Inferno service to Plan 9 service registry +.SH SYNOPSIS +.B 9srvfs +[ +.BI -p " perm" +] +.I srvname +.I source +.SH DESCRIPTION +.I 9srvfs +is only usable (or indeed of interest) on Inferno hosted under Plan 9. +It uses +.IR srv9 (3) +to make an Inferno service +.I source +available to Plan 9 applications via the Plan 9 service registry. +.I Srv9 (3) +must previously have been bound to +.B /srv +in the current name space, with +.B -c +to allow file creation (see +.IR bind (1)). +.PP +.I Source +may be either a command or the name of a directory. +If +.I source +is surrounded by braces +.RB ( { +and +.BR } ), +it is invoked as a +.IR sh (1) +command, and its standard input (sic) is posted as Plan 9 service +.BI /srv/ srvname +with permissions +.I perm +(default: mode 600). +Otherwise, +.I source +is taken to be a directory that is the root of a name space to export to Plan 9, +an exporting file service is started (see +.IR sys-export (2)), +and again posted as Plan 9 service +.BI /srv/ srvname, +and the export terminates when the Plan 9 service file +has been removed and the last mounted instance goes away in Plan 9. +.SH EXAMPLE +Make the current Inferno environment variables available to Plan 9 applications: +.IP +.EX +bind -c '#₪' /srv # if not already done +9srvfs infenv /env +.EE +.PP +The name space can then be mounted in Plan 9, +allowing variables to be read and written in that Inferno environment: +.IP +.EX +mount -c /srv/infenv /n/ftp +ls /n/ftp +cat /n/ftp/emuargs +echo masked man >/n/ftp/zorro +.EE +.SH SOURCE +.B /appl/cmd/9srvfs.b +.SH SEE ALSO +.IR bind (1), +.IR srv9 (3), +.IR import (4) diff --git a/man/4/INDEX b/man/4/INDEX new file mode 100644 index 00000000..61e69196 --- /dev/null +++ b/man/4/INDEX @@ -0,0 +1,30 @@ +intro 0intro +9srvfs 9srvfs +acme acme +archfs archfs +cpu cpu +dbfs dbfs +rawdbfs dbfs +9660srv dossrv +dossrv dossrv +export export +factotum factotum +feedkey factotum +ftpfs ftpfs +9export import +import import +iostats iostats +keyfs keyfs +keysrv keysrv +kfs kfs +lockfs lockfs +logfile logfile +memfs memfs +mntgen mntgen +namespace namespace +palmsrv palmsrv +ramfile ramfile +registry registry +regquery registry +spree spree +tarfs tarfs diff --git a/man/4/acme b/man/4/acme new file mode 100644 index 00000000..092d01dc --- /dev/null +++ b/man/4/acme @@ -0,0 +1,406 @@ +.TH ACME 4 +.SH NAME +acme \- control files for text windows +.SH SYNOPSIS +.B acme +[ +.B -f +.I varfont +] [ +.B -F +.I fixfont +] +[ +.I file +\&... ] +.SH DESCRIPTION +The text window system +.IR acme (1) +serves a variety of files for reading, writing, and controlling +windows. +Some of them are virtual versions of system files for dealing +with the virtual console; others control operations +of +.I acme +itself. +When a command is run under +.IR acme , +a directory holding these files is mounted on +.B /mnt/acme +(also bound to +.BR /chan ) +and also +.BR /dev/acme ; +the files mentioned here +appear in both these directories. +.PP +Some of these files supply virtual versions of services available from the underlying +environment, in particular the character terminal files +.IR cons (3). +Other files are unique to +.IR acme . +.TP +.B acme +is a subdirectory used by +.B win +(see +.IR acme (1)) +as a mount point for the +.I acme +files associated with the window in which +.B win +is running. +It has no specific function under +.I acme +itself. +.TP +.B cons +is the standard and diagnostic output file for all commands +run under +.IR acme . +(Input for commands is redirected to +.BR /dev/null .) +Text written to +.B cons +appears in a window labelled +.IB dir /+Errors\f1, +where +.I dir +is the directory in which the command +was run. +The window is created if necessary, but not until text is actually written. +.TP +.B consctl +Is an empty unwritable file present only for compatibility. +.TP +.B index +holds a sequence of lines of text, one per window. Each line has 5 decimal numbers, +each formatted in 11 characters plus a blank\(emthe window ID; +number of characters (runes) in the tag; +number of characters in the body; +a 1 if the window is a directory, 0 otherwise; +and a 1 if the window is modified, 0 +otherwise\(emfollowed by the tag up to a newline if present. +Thus at character position 5×12 starts the name of the window. +If a file has multiple zeroxed windows open, +only the most recently used will appear in the +.B index +file. +.TP +.B label +is an empty file, writable without effect, present only for compatibility. +.TP +.B new +A directory analogous to the numbered directories +.RI ( q.v. ). +Accessing any +file in +.B new +creates a new window. Thus to cause text to appear in a new window, +write it to +.BR /dev/new/body . +For more control, open +.BR /dev/new/ctl +and use the interface described below. +.LP +.PP +Each +.I acme +window has associated a directory numbered by its ID. +Window IDs are chosen sequentially and may be discovered by the +.B ID +command, by +reading the +.B ctl +file, or +indirectly through the +.B index +file. The files in the numbered directories are as follows. +.TP +.B addr +may be written with any textual address (line number, regular expression, etc.), +in the format understood by button 3 but without the initial colon, including compound addresses, +to set the address for text accessed through the +.B data +file. +When read, it returns the value of the address that would next be read +or written through the +.B data +file, in the format +.BI # m ,# n +where +.I m +and +.I n +are character (not byte) offsets. If +.I m +and +.I n +are identical, the format is just +.BI # m\f1. +Thus a regular expression may be evaluated by writing it to +.B addr +and reading it back. +The +.B addr +address has no effect on the user's selection of text. +.TP +.B body +holds contents of the window body. It may be read at any byte offset. +Text written to +.B body +is always appended; the file offset is ignored. +.TP +.B ctl +may be read to recover the five numbers as held in the +.B index +file, described above. +Text messages may be written to +.B ctl +to affect the window. +Each message is terminated by a newline and multiple +messages may be sent in a single write. +.RS .5i +.TF "dumpdir\ directory" +.TP +.B addr=dot +Set the +.B addr +address to that of the user's selected text in the window. +.TP +.B clean +Mark the window clean as though it has just been written. +.TP +.B cleartag +Remove all text in the tag after the vertical bar. +.TP +.B del +Equivalent to the +.B Del +interactive command. +.TP +.B delete +Equivalent to the +.B Delete +interactive command. +.TP +.B dot=addr +Set the user's selected text in the window to the text addressed by the +.B addr +address. +.TP +.BI dump " command +Set the command string to recreate the window from a dump file. +.TP +.BI dumpdir " directory +Set the directory in which to run the command to recreate the window from a dump file. +.TP +.B get +Equivalent to the +.B Get +interactive command with no arguments; accepts no arguments. +.TP +.B limit=addr +When the +.B ctl +file is first opened, regular expression context searches in +.B addr +addresses examine the whole file; this message restricts subsequent +searches to the current +.B addr +address. +.TP +.B mark +Cancel +.BR nomark , +returning the window to the usual state wherein each modification to the +body must be undone individually. +.TP +.BI name " name +Set the name of the window to +.IR name . +.TP +.B nomark +Turn off automatic `marking' of changes, so a set of related changes +may be undone in a single +.B Undo +interactive command. +.TP +.B noscroll +Turn off automatic `scrolling' of the window to show text written to the body. +.TP +.B put +Equivalent to the +.B Put +interactive command with no arguments; accepts no arguments. +.TP +.B scroll +Cancel a +.B noscroll +message, returning the window to the default state wherein each write +to the +.B body +file causes the window to `scroll' to display the new text. +.TP +.B show +Guarantee at least some of the selected text is visible on the display. +.TP +.B noecho +Stop echoing characters sent to the window but indicate their presence by +printing an asterisk. +.TP +.B echo +Turns +.BR noecho +off. +.RE +.PD +.TP +.B data +is used in conjunction with +.B addr +for random access to the contents of the body. +The file offset is ignored when writing the +.B body +file, but the character (not byte) offset may be set with +.B addr +and then read from the +.B data +file. +Text, which must contain only whole characters (no `partial runes'), +written to +.B data +replaces the characters addressed by the +.B addr +file and sets the address to the null string at the end of the written text. +A read from +.B data +returns as many whole characters as the read count will permit starting +at the beginning of the +.B addr +address (the end of the address has no effect) +and sets the address to the null string at the end of the returned +characters. +.TP +.B event +When a window's +.B event +file is open, changes to the window occur as always but the +actions are also reported as +messages to the reader of the file. Also, user actions with buttons 2 and 3 +(other than chorded +.B Cut +and +.BR Paste , +which behave normally) have no immediate effect on the window; +it is expected that the program reading the +.B event +file will interpret them. +The messages have a fixed format: +a character indicating the origin or cause of the action, +a character indicating the type of the action, +four free-format blank-terminated decimal numbers, +optional text, and a newline. +The first and second numbers are the character addresses of the action, +the third is a flag, +and the final is a count of the characters in the optional text, which +may itself contain newlines. +The origin characters are +.B E +for writes to the +.B body +or +.B tag +file, +.B F +for actions through the window's other files, +.B K +for the keyboard, and +.B M +for the mouse. +The type characters are +.B D +for text deleted from the body, +.B d +for text deleted from the tag, +.B I +for text inserted to the body, +.B i +for text inserted to the tag, +.B L +for a button 3 action in the body, +.B l +for a button 3 action in the tag, +.B X +for a button 2 action in the body, and +.B x +for a button 2 action in the tag. +.IP +If the relevant text has less than 256 characters, it is included in the message; +otherwise it is elided, the fourth number is 0, and the program must read +it from the +.B data +file if needed. No text is sent on a +.B D +or +.B d +message. +.IP +For +.BR D , +.BR d , +.BR I , +and +.BR i +the flag is always zero. +For +.BR X +and +.BR x , +the flag is a bitwise OR (reported decimally) of the following: +1 if the text indicated is recognized as an +.I acme +built-in command; +2 if the text indicated is a null string that has a non-null expansion; +if so, another complete message will follow describing the expansion +exactly as if it had been indicated explicitly (its flag will always be 0); +8 if the command has an extra (chorded) argument; if so, +two more complete messages will follow reporting the argument (with +all numbers 0 except the character count) and where it originated, in the form of +a fully-qualified button 3 style address. +.IP +For +.B L +and +.BR l , +the flag is the bitwise OR of the following: +1 if +.I acme +can interpret the action without loading a new file; +2 if a second (post-expansion) message follows, analogous to that with +.B X +messages; +4 if the text is a file or window name (perhaps with address) rather than +plain literal text. +.IP +For messages with the 1 bit on in the flag, +writing the message back to the +.B event +file, but with the flag, count, and text omitted, +will cause the action to be applied to the file exactly as it would +have been if the +.B event +file had not been open. +.TP +.B tag +holds contents of the window tag. It may be read at any byte offset. +Text written to +.B tag +is always appended; the file offset is ignored. +.SH SOURCE +.B /appl/acme +.br +.B /appl/acme/acme +.SH SEE ALSO +.IR acme (1), +.IR cons (3) diff --git a/man/4/archfs b/man/4/archfs new file mode 100644 index 00000000..308d95dc --- /dev/null +++ b/man/4/archfs @@ -0,0 +1,64 @@ +.TH ARCHFS 4 +.SH NAME +archfs \- mount a mkfs archive +.SH SYNOPSIS +.B archfs +[ +.B -ab +] [ +.B -s +] [ +.B -m mountpoint +] +.I archfile +[ +.I prefix ... +] +.SH DESCRIPTION +.I Archfs +mounts at +.IR mountpoint +(default: +.BR /mnt/arch ), +a read-only file system representing the contents of +.IR archfile , +which is a file of the format produced by +.IR mkfs (8) +with the +.B -a +option. +Typically the archive file will have been created by +.IR mkfs (8) +or +.IR create (8). +Any +.I prefix +names limit the file system's contents to files and directories in the +archive whose path names start with one of the prefixes. +.PP +The +.B -a +and +.B -b +options cause the archive contents to be mounted after or before the +mount point's existing contents, in a union dirctory (see +.IR bind (1) +for details). +Normally the archive contents replace the contents of +.IR mountpoint . +The +.B -s +option causes the rest of the archive to be skipped once a file is found in the archive which +does not start with any of the given prefixes. This is useful an archive is known to start +with a description of its contents (eg, the +.B /wrap +directory provided by +.IR create (8)), +and that is all that is needed under +.IR mountpoint . +.SH SOURCE +.B /appl/cmd/archfs.b +.SH SEE ALSO +.IR tarfs (4), +.IR mkfs (8), +.IR create (8) diff --git a/man/4/cpu b/man/4/cpu new file mode 100644 index 00000000..e6de49c4 --- /dev/null +++ b/man/4/cpu @@ -0,0 +1,141 @@ +.TH CPU 4 +.SH NAME +cpu \- cpu server resource +.SH SYNOPSIS +.B grid/srv/cpu +.br +.B grid/runcpu +.SH DESCRIPTION +.I Cpu +is a file server that provides a processing resource. This resource imports a namespace from one or more external sources and executes selected commands within it. +.I Cpu +creates its own namespace containing three files +.BR ctl , +.B cmd +and +.B ns +which are used to configure the processing task prior to execution, this namespace is exported and served on +.I stdin. +In order to configure a processing task, a client must first mount the +.I cpu +namespace. Once this is done, reading the +.B cmd +and +.B ns +files will display the current configuration of commands to be executed or directories to be imported respectively. The +.B ctl +file is used to modify the current configuration and accepts the following input: +.IP +.B add cmd +.I command +.IP +.B add ns +.I path address +.IP +.B del [cmd|ns] +.I index +.PP +Where +.I command +is the name (including full path and parameters) of a command to be executed. +.I Path +is the name of a directory to import from the exported namespace available at +.I address +and +.I index +is the index (as shown when reading the +.B cmd +and +.B ns +files) of the command or directory to be removed from the configuration. +.PP +For example, to import +.B /dis +and +.B /dev +from a resource exporting a Styx (see +.IR intro(5)) +namespace at address +.B tcp!200.1.5.53!7003 +and then run +.B ls -l +and +.BR du , +the following commands would be used: +.IP +.B "echo 'add cmd /dis/ls -l' > ctl" +.br +.B "echo 'add cmd /dis/du' > ctl" +.br +.B "echo 'add ns /dis tcp!200.1.5.53!7003' > ctl" +.br +.B "echo 'add ns /dev tcp!200.1.5.53!7003' > ctl" +.PP +Reading the +.B cmd +and +.B ns +files will give the following output: +.IP +.B cmd +.br +.B 1: /dis/ls -l +.br +.B 2: /dis/du +.IP +.B ns +.br +.B 1: /dis (200.1.5.53!7003) +.br +.B 2: /dis (200.1.5.53!7003) +.PP +Once the client disconnects from (unmounts) the cpu, the selected namespaces will be imported and the commands executed. Note: A +.I cpu +does not have +.I any +namespace of its own. All required namespaces +.I must +be imported, for a simple command such as +.BR ls , +the minimum recommended namespace to import would be: +.B /chan /dev /dis /module +.PP +.IR Register (1) +may be used in conjunction with +.I cpu +to register it with a +.IR registry(4) +and to export and serve its namespace across +.IR dial(2) +network connections. Incoming connections may also be displayed visually using +.IR monitor (1). +For example: +.PP +.BI "grid/register [" " options ..." " ] { grid/srv/cpu } | grid/srv/monitor 2 'CPU resource' +.PP +This set of commands is encapsulated within the shell script +.I runcpu +which will automatically register +.I cpu +with a +.IR registry(4) +if possible and start up the graphical display to show connections to the resource. There is no need for the user to execute +.I cpu +outside of +.I runcpu +unless the namespace it provides is required to be accessible in a different way to that provided by +.IR register (1). +.SH SOURCE +.B /appl/grid/srv/cpu.b + +.SH BUGS +At the moment, +.I Cpu +will only import namespaces across an unauthenticated connection as provided by +.IR ns (1). + +.SH "SEE ALSO" +.IR monitor (1), +.IR ns (1), +.IR register (1), +.IR session (1) diff --git a/man/4/dbfs b/man/4/dbfs new file mode 100644 index 00000000..e810ca9b --- /dev/null +++ b/man/4/dbfs @@ -0,0 +1,127 @@ +.TH DBFS 4 +.SH NAME +dbfs, rawdbfs \- simple database file system +.SH SYNOPSIS +.B dbfs +[ +.B -abcer +] +.I file mountpoint +.br +.B rawdbfs +[ +.B -abcelrx +] +[ +.B -u +.I cmd +] +.I file mountpoint +.PP +.IB mountpoint /new +.br +.IB mountpoint /0 +.br +.IB mountpoint /1 +.br +.IB mountpoint /\fR...\fP +.SH DESCRIPTION +.B Dbfs +and +.B rawdbfs +both expose a simple, record-based filesystem stored +in +.IR file . +The +.BR -a , +.BR -b , +.BR -c , +and +.B -r +options have the same meaning as the options accepted by +.IR bind (1). +If the +.B -e +option is given, then +.I file +will be created if it does not already exist. +The filesystem provided by both +.B dbfs +and +.B rawdbfs +is substantially the same: +when started, +.I mountpoint +is populated with numbered files, one for each record found in +.IR file . +A read of one of these files yields the data in the record; +a write stores data in the record. A new record can be created +by opening the +.B new +file; writes to this file write to the new record. The name +of the new file can be discovered by using +.I fstat +in +.IR sys-stat (2). +Records can be removed by removing the appropriate +record file. +.PP +.B Rawdbfs +has additional features for database use: +.BR -x +causes two additional files ("index" and "stats") to appear +in the mounted directory, +.BR -l +specifies that a record can only be opened for writing +by one process at once, and +.BR -u +.I cmd +specifies a +.IR sh (1) +command to be run whenever the contents of the database +change. +The index file is provided as a convenience for database +client applications. Once initialised (by writing an integer value to it), +subsequent reads return an ever-increasing integer value. +Reading the stats file returns counts of database +read, write, create and delete operations as a string of four +integers. +.PP +.B Dbfs +and +.B rawdbfs +differ in the way that they store their data. +.B Dbfs +stores its records in +.I file +in a simple text format: the end of a record is indicated +by an empty line. The file is completely rewritten every time +a record is written. Storing records containing blank lines +will lead to confusion when the database is re-read. +.B Rawdbfs +can store arbitrary data, but the format of the data +storage is known only to itself. It does not rewrite +the whole file on every record change, so can be more +suitable for flash-based storage, where it is important +to minimise the number of writes. +.PP +Note that the record numbers always get their initial +numbering from the order of the records in +.IR file . +You cannot assume that the filename given to a record +will remain the same between runs of +.BR dbfs . +.SH SOURCE +.B /appl/cmd/dbfs.b +.br +.B /appl/cmd/rawdbfs.b +.SH SEE ALSO +.IR memfs (4), +.IR ramfile (4), +.IR wm-calendar (1) +.SH BUGS +Write offsets are ignored, so the maximum amount of data +that can be stored in a record is ATOMICIO bytes (i.e. 8K). +.PP +There is no way to compact a file maintained by +.BR dbfs . diff --git a/man/4/dossrv b/man/4/dossrv new file mode 100644 index 00000000..5fd2cc3a --- /dev/null +++ b/man/4/dossrv @@ -0,0 +1,76 @@ +.TH DOSSRV 4 +.SH NAME +dossrv, 9660srv \- DOS/Windows and ISO 9660 file systems +.SH SYNOPSIS +.B dossrv +.RB [ \-v ] +.RB [ \-s ] +.RB [ \-F ] +.RB [ \-c ] +[ +.BI -f " devicefile" +] +[ +.BI -m " mountpoint" +] +[ +.BI -S " sectors/track" +] +.PP +.B 9660srv +.RB [ \-rab ] +.I cdfile +.I dir +.SH DESCRIPTION +.I Dossrv +makes the contents of a DOS/Windows file system visible in the Inferno name space. +The options are: +.TP +.B -v +print a debugging trace, including Styx messages, on standard error +.TP +.B -F +display FAT information +.TP +.B -c +display cluster data and I/O activity +.TP +.B -s +standard ouput is connected to a client; serve that +.TP +.BI -f " devicefile" +the DOS/Windows file system image; defaults to +.BR /dev/hd0disk . +.TP +.BI -m " mountpoint" +The directory where the contents of the file system should appear; defaults to +.BR /n/dos . +.TP +.BI -S " sectors/track" +The number of sectors per track. The default is 9. +.PP +.I 9660srv +performs a similar function for files (notably CDROMs) in ISO9660 format, +including the Rock Ridge extension and its Plan 9 variant. +It makes the contents of +.I cdfile +visible in the name space at +.IR dir . +The options are those of +.IR bind (1): +.BR \-r , +to replace the contents of +.IR dir ; +.BR \-a , +to make a union directory with the CD contents after the contents of +.IR dir ; +.BR \-b , +to make a union directory with the CD contents before the contents of +.IR dir . +.SH SOURCE +.B /appl/cmd/dossrv.b +.br +.B /appl/cmd/9660srv.b +.SH BUGS +.I Dossrv +cannot handle all the FAT32 extensions. diff --git a/man/4/export b/man/4/export new file mode 100644 index 00000000..ea2fdf39 --- /dev/null +++ b/man/4/export @@ -0,0 +1,69 @@ +.TH EXPORT 4 +.SH NAME +export \- export name space on a connection +.SH SYNOPSIS +.B export +[ +.B \-a +] [ +.B \-n +] +.I dir +[ +.I file +] +.SH DESCRIPTION +.I Export +calls +.B Sys->export +(see +.IR sys-dial (2)) +to serve a name space rooted at +.I dir +over a connection to a Styx client. +.I Export +opens the connection on the given +.IR file , +or uses the standard input by default. +It returns when the client closes the connection. +If the +.B \-a +option is given, however, +.I export +starts an Inferno kernel process +to serve the name space and returns immediately. +.PP +Normally, +.I export +forks the current name space, and makes +.I dir +the root of its copy. +Changes subsequently made to the current name space will +not be visible to clients of +.IR export . +If the +.B \-n +option is given, however, and +.I dir +is the root +.RB (` / '), +.I export +serves the current name space without forking it; changes made to it +will be visible to clients. +.PP +.I Export +starts serving Styx immediately; it assumes that the connection +has been authenticated if required. +.SH EXAMPLE +Start a background process to serve the name space on the serial port. +.IP +.B "export / /dev/eia0 &" +.PP +Although useful when bootstrapping a system, this is unsafe +unless a transport protocol is run on the connection. +.SH SOURCE +.B /appl/cmd/export.b +.SH SEE ALSO +.IR cpu (1), +.IR sys-dial (2), +.IR intro (5) diff --git a/man/4/factotum b/man/4/factotum new file mode 100644 index 00000000..867206b6 --- /dev/null +++ b/man/4/factotum @@ -0,0 +1,717 @@ +.TH FACTOTUM 4 +.SH NAME +factotum, feedkey \- authentication agent +.SH SYNOPSIS +.B auth/factotum +[ +.B -d +.\" ] [ +.\" .B -a authaddr +] [ +.B -s +.I srvname +] [ +.B -m +.I mtpt +] +.B ... +.IB attribute ? +.B ... +.PP +.B auth/feedkey +.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 +serves +.IR srv (3) +directory +.BR #sfactotum , +which it binds to +.BR /mnt/factotum . +It serves 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, including the one normally +used by Inferno, the +authentication is mutual. +Proof is accomplished using secret information kept by +.I 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 +.\" .IR authsrv (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 +currently supports the following protocols: +.TF mschap +.TP +.B infauth +Inferno's authentication protocol +.IR auth (6) +.TP +.B p9any +a metaprotocol used to negotiate which actual protocol to use. +.TP +.B p9sk1 +a Plan 9 shared key protocol described in +.I authsrv +in section 6 of Plan 9's Programmer's Manual +.\" .TP +.\" .B p9sk2 +.\" a variant of +.\" .B p9sk1 +.\" described in +.\" .IR authsrv (6)'s +.\" ``Remote Execution'' section. +.\" .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 +.\" .IR cs (8), +.\" the file +.\" .IB net /ndb , +.\" and finally the network database +.\" .IR ndb (6). +.TP +.B \-m +specifies the mount point to use, by default +.BR /mnt/factotum . +.TP +.B \-s +specifies the service name to use, +by default it is +.BR factotum . +.TP +.B \-d +turns on debugging, written to standard error. +.PD +.PP +.I Feedkey +is a +.IR wm (1) +user interface for +.\" confirming key usage and +entering new keys. It puts its window in the +.IR wm (1) +toolbar, +and waits, reading requests from +.\" .B confirm +.\" and +.BR needkey . +For each request, it pops open a window containing suitable prompts 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. Values containing spaces must be quoted following +the conventions of +.IR sh (1). +An attribute whose name begins with an exclamation point +.RB ( ! ) +is `secret' and +does not appear when reading the +.B ctl +file. +See the `Protocols' section below. +Here are some examples: +.PP +.EX + proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent + proto=pass user=tb !password=does.it.matter +.EE +.PP +The required attributes depend on the authentication protocol. +The `Protocols' section below describes the attributes specific +to each supported protocol. +.PP +All keys can have additional attributes that act either as comments +or as selectors to distinguish them in the +.IR factotum (2) +and other +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. +.PP +If a key has a +.B disabled +attribute (with any value), the key is not used +during any protocols. +.\" Factotum automatically marks +.\" keys with +.\" .B disabled=by.factotum +.\" when they fail during certain authentication +.\" protocols (in particular, the Plan 9 ones). +.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 +.IR factotum , +such as those in +.IR factotum (2), +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 +.I 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 messages are: +.TP +.B "key \fIattribute-value-list\fP +add a new key. This will replace any old key whose +public attributes match (ie, non +.B ! +attributes). +.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 factotum (2)). +.PP +The RPC protocol is normally embodied by one of the +routines in +.IR factotum (2). +We describe it here should anyone want to extend +that module. +.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 factotum (2)) +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 will not appear if the +.B needkey +file is in use. +Otherwise, a suitable key can be written to +.B ctl +and after that, +authentication may proceed (ie, 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 +.SS Protocols +.I Factotum +can support many authentication protocols, each implemented by a separate +module in the directory +.BR /dis/auth/proto . +Currently only a few are implemented in Inferno: +.PP +.B Infauth +is the Inferno public-key authentication protocol described by +.IR auth (6). +It requires a key with +.BR proto = infauth , +and a +.B !authinfo +attribute providing Inferno authentication data as an S-expression (see +.IR sexprs (6)). +The S-expression has five string elements: +the signer's public key, the certificate for the user's public key, +the user's secret key, and the values for parameters +.I alpha +and +.IR p , +selected by the signer when the key was generated. +The keys and certificates are represented as strings of the form produced by +.IR keyring-certtostr (2); +the parameter values are represented as binary in the form produced by +.B IPint.iptobytes +(see +.IR keyring-ipint (2)). +Normally +.B infauth +checks that the other party's key was signed by the signer in the +.B !authinfo +data, but +if the key has the attribute +.B anysigner +with non-zero integer value, +.B infauth +will accept keys signed by any signer. +The actual signer can be determined by inspecting the data +returned by the +.B authinfo +request; +the option is intended for use by services that support calls from many domains, +each with its own signer. +.PP +.BR P9sk1 +is the shared-secret protocol used to authenticate to various Plan 9 services. +It requires 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. +.B P9sk1 +normally is invoked by Plan 9's general authentication protocol, +.BR p9any , +which is supported by Inferno's +.IR factotum . +.PP +.B Pass +requires a key with +.B proto=pass +in addition to +.B user +and +.B !password +attributes. +.\" .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. +.SH SOURCE +.B /appl/cmd/auth/factotum +.SH SEE ALSO +.IR factotum (2) diff --git a/man/4/ftpfs b/man/4/ftpfs new file mode 100644 index 00000000..522adb4b --- /dev/null +++ b/man/4/ftpfs @@ -0,0 +1,117 @@ +.TH FTPFS 4 +.SH NAME +ftpfs \- file transfer protocol (FTP) file server +.SH SYNOPSIS +.B ftpfs +[ +.B -/dpq +] [ +.BI -m " mountpoint" +] [ +.BI -a " password" +] +.I ftphost +.SH DESCRIPTION +.I Ftpfs +connects to +.I ftphost +using the Internet's File Transfer Protocol, +and makes the remote files +visible at +.I mountpoint +(default: +.BR /n/ftp ) +in the current name space, +for access by ordinary Inferno file operations. +In other words, it is a protocol translator between FTP and Styx. +The connection is shut down by unmounting the mount point; +see +.IR bind (1). +The +.I ftphost +can be any address acceptable to +.IR cs (8); +the default network is +.BR tcp , +and the default service is +.B ftp +(port 21). +.PP +.I Ftpfs +will prompt for a user name and password as +.I ftphost +demands. +If the FTP host supports `anonymous FTP' (ie, guest access), +it will accept the user name +.L anonymous +and a conventional password (notionally the user's e-mail address). +Given the +.B -a +option, +.I ftpfs +automatically logs in as +.L anonymous +with the +.I password +supplied, +avoiding prompting. +.PP +By default, +.I ftpfs +uses a `passive' connection for file transfer: the remote system gives the local +system a new address to call to fetch the data. +This often works best for local systems behind firewalls that block incoming calls +to arbitrary ports, +but can fail for instance if the remote system does not support passive mode, +or is itself behind such a firewall. +The +.B \-p +option forces `active' connection: the local system gives the remote machine +an address on which to call it back to transfer the data. +.PP +Other options are: +.TP +.B \-/ +Mount the remote machine's root directory on +.IR mountpoint , +not the user's home directory (which is used by default). +.TP +.B \-q +Suppress the printing of chatter (`informational messages') from +the remote server. +.TP +.B \-d +Display all FTP protocol transactions to allow a failure to connect to be debugged. +.\" -/? +.PP +.I Ftpfs +keeps a limited local cache of remote files and directories. +The cache is kept consistent with file and directory operations by the local +user through the current connection, but not with changes made by others on the remote site. +Cached entries for a given directory can be flushed explicitly by +accessing the name +.B .flush.ftpfs +in that directory. +.SH EXAMPLE +Mount a remote machine and copy files from there to here. +.IP +.EX +mkdir here +ftpfs -a 'bloggs@' ftp.vitanuova.com +cp /n/ftp/package.tgz here +unmount /n/ftp +.EE +.SH FILES +.TF /tmp/ftp.* +.TP +.B /tmp/ftp.* +Temporarily cached files +.SH SOURCE +.B /appl/ftpfs +.SH BUGS +Symbolic links are not supported. +.br +.I Ftpfs +does not implement `rename', forcing +.IR mv (1) +to rename by copying. diff --git a/man/4/import b/man/4/import new file mode 100644 index 00000000..e7465edb --- /dev/null +++ b/man/4/import @@ -0,0 +1,148 @@ +.TH IMPORT 4 +.SH NAME +import, 9export \- exchange name spaces with a Plan 9 system +.SH SYNOPSIS +.B import +[ +.B -ab +] [ +.B -c +] [ +.BI -k " keyspec" +] [ +.BI -e " crypt hash" +] +.I host +.I file +[ +.I localfile +] +.PP +.B 9export +[ +.B -A +] [ +.BI -k " keyspec" +] [ +.BI -e " crypt hash" +] +.SH DESCRIPTION +.I Import +dials the Plan 9 +.I host +(which might be the current host) and makes the given +.I file +on that system visible in the local name space as +.I localfile +(if +.I localfile +is not given, +.I file +is used as the local name). +It requires that the user's Plan 9 authentication agent, +.IR factotum , +appear in the Inferno name space at +.BR /mnt/factotum . +(That is why +.I import +is currently limited to use when Inferno is hosted on Plan 9, +until Inferno has an equivalent to +.IR factotum .) +The remote files are accessed with the permissions of the user authenticated +to the remote system by +.IR factotum . +.PP +If the remote +.I file +is a directory, the whole file tree rooted at that +directory is accessible, the local mount point must also be a directory, +and the +.BR -a , +.BR -b , +and +.B -c +options control the creation of union directories just as for +.IR bind (1). +By default, the remote file replaces the local one in the name space. +.PP +If the +.B -e +option is given, the network connection can be encrypted, or provided +with digests to authenticate the contents, or both. +.I Crypt +is an encryption algorithm accepted by +.IR ssl (3); +.I hash +is one of its digest algorithms. +Plan 9's +.I exportfs +normally requires +.B +\&'rc4_256 sha1' +on such connections; +it currently provides no negotiation of algorithms. +.PP +The +.B -k +option gives a string of space separated +.IB attr = value +pairs that control +.IR factotum 's +selection of a suitable key for the remote system. +.PP +.I 9export +serves the Plan 9 +.I exportfs +protocol on its standard input, +allowing a Plan 9 system to import parts of the Inferno name space in which +.I 9export +is run. +If the +.B -A +option is given, the caller is not authenticated, line encryption and message authentication +are not done, +and the Plan 9 +.I exportfs +protocol starts immediately. +Otherwise, the Plan 9 authentication agent +.I factotum +must be accessible via +.B /mnt/factotum +as for +.IR import , +and it is used to run the Plan 9 authentication protocol. +The +.B -e +and +.B -k +options are as for +.IR import . +Normally +.I 9export +returns when the client closes the connection; the +.B -a +option causes +.I 9export +to return immediately, leaving a kernel process to serve the name space. +.I 9export +might be used as follows: +.IP +.EX +listen -Av 'tcp!*!exportfs' {9export&} +.EE +.PP +Beware that currently the name space is served with the permissions of the +person running +.IR 9export , +not those of the caller. +.SH SOURCE +.B /appl/cmd/9export.b +.br +.B /appl/cmd/import.b +.SH SEE ALSO +.IR bind (1), +.IR factotum (2), +.IR export (4), +.IR namespace (6) +.SH BUGS +Temporarily limited to Plan 9 hosted environment only. diff --git a/man/4/iostats b/man/4/iostats new file mode 100644 index 00000000..e4a3b4fb --- /dev/null +++ b/man/4/iostats @@ -0,0 +1,81 @@ +.TH IOSTATS 4 +.SH NAME +iostats \- file system to measure I/O +.SH SYNOPSIS +.B iostats +[ +.B -d +] +[ +.B -f +.I dbfile +] +.I cmd +[ +.I args... +] +.SH DESCRIPTION +.I Iostats +is a file server that interposes itself between a program and a copy of the current name space, +which allows it to gather statistics of file system +use at the level of the file system protocol of +.IR intro (5). +When the program exits, +a report is printed on standard error. +.PP +The report consists of three sections. +The first section reports the amount +of user data in +.B read +and +.B write +messages sent by the program and the average rate at +which the data was transferred. +The +.B protocol +line reports the amount +of data sent as message headers, that is, +protocol overhead. +The +.B rpc +line reports the +total number of file system transactions. +.PP +The second section gives +the number of messages, the fastest, slowest, and average turn around +time and the amount of data involved with each 9P +message type. +The final section gives an I/O summary for each file used +by the program in terms of opens, reads and writes. +.PP +The +.B -d +option causes +.I iostats +to write a debugging log to +.I dbfile +(default: +.BR iostats.out ) +that records all protocol messages. +.SH EXAMPLE +Display summary of file I/O incurred by +.IR ls (1): +.IP +.EX +iostats ls +.EE +.PP +Start a new shell, displaying all Styx traffic caused by the shell or its children: +.IP +.EX +iostats -df /fd/1 sh +.EE +.SH SOURCE +.B /appl/cmd/iostats.b +.SH BUGS +Poor clock resolution means that large amounts of I/O must be done to +get accurate rate figures. +.PP +Can be fooled by programs that do fresh mounts outside its purview. +.PP +Cannot monitor standard input or output. diff --git a/man/4/keyfs b/man/4/keyfs new file mode 100644 index 00000000..51bfb48a --- /dev/null +++ b/man/4/keyfs @@ -0,0 +1,116 @@ +.TH KEYFS 4 +.SH NAME +keyfs \- encrypted key storage +.SH SYNOPSIS +.B auth/keyfs +[ +.B -D +] +[ +.B -m mountpoint +] [ +.I keyfile +] +.SH DESCRIPTION +.I Keyfs +serves a two-level name space for storing authentication data, specifically +the status and secrets of each user to whom +.IR logind (8) +can issue a certificate. +The data is stored in +.I keyfile +(default: +.BR /keydb/keys ), +encrypted by a master key using AES +(see +.IR keyring-crypt (2)). +.I Keyfs +should be started only on the machine acting as authentication server (signer), +before a listener is started for +.IR signer (8). +Note that +.I signer +and +.I keyfs +must share the name space. +Furthermore, no other application except the console should see that name space. +.PP +.I Keyfs +prompts for the master key, reads and decrypts +.IR keyfile , +and serves files representing the contents at +.I mountpoint +in the name space (default: +.BR /mnt/keys ). +.PP +Each +.I user +in +.I keyfile +is represented by a directory +.IB mountpoint / user. +Each such directory has the following files: +.TF status +.TP +.B log +A count of the number of failed authentications. +Writing +.B bad +to the file increments the count; writing +.B good +resets it to 0. +When the count reaches some implementation-defined limit, +the account status is set to +.B disabled +(see the +.B status +file below). +.TP +.B expire +The time in seconds since the epoch when the account will expire, +or the text +.B never +if it has no expiration time. +The string +.B never +or a number can be written to the file to set a new expiry time. +.TP +.B secret +The secret (supposedly) known only to the user and the authentication service. +A secret is any sequence of bytes between 0 and 255 bytes long; +it is initially empty. +The length of the file returned by +.IR sys-stat (2) +is the length of the secret. +If the account has expired or is disabled, an attempt to read the file +will give an error. +.TP +.B status +The current status of the user's account, either +.B ok +or +.BR disabled . +Either string can be written to the file to change the state accordingly. +.PD +.PP +To add a new account, make a directory with that name in +.IR mountpoint . +It must not already exist. +To remove an account, remove the corresponding directory; +to rename an account, rename the directory. +.PP +All changes made via file system operations in +.I mountpoint +result in appropriate changes to +.IR keyfile . +.PD +.PP +The +.B -D +option enables tracing of the file service protocol, for debugging. +.SH SOURCE +.B /appl/cmd/auth/keyfs.b +.SH SEE ALSO +.IR changelogin (8), +.IR login (8), +.IR signer (8) diff --git a/man/4/keysrv b/man/4/keysrv new file mode 100644 index 00000000..2b12d43a --- /dev/null +++ b/man/4/keysrv @@ -0,0 +1,116 @@ +.TH KEYSRV 4 +.SH NAME +keysrv \- secret key server +.SH SYNOPSIS +.B auth/keysrv +.SH DESCRIPTION +.I Keysrv +is a file service run on a connection to an authentication server. +It allows a remote user +to change a secret stored on the server by +.IR keyfs (4), +which must have been started before +.IR keysrv , +in a name space with the authentication data available under +.BR /mnt/keys . +.PP +.I Keysrv +serves a single file, +.BR secret , +on a connection accessed through file descriptor 0 (ie, the standard `input'). +When invoked, it +first authenticates the connection using +.IR security-auth (2), +requiring the client to use +.B sha1 +and +.BR rc4_256 . +If authentication succeeds, +.I keysrv +exports a name space containing a file +.BR secret . +The authentication ensures that only a user that possesses a valid certificate can connect to the service. +.PP +If the authenticated user (ie, the user name in the verified certificate) +has an entry in +.BR /mnt/keys , +as served by +.IR keyfs (4), +and that user has a non-empty secret, +then the file +.B secret +will accept reads and writes. +(Otherwise, every read or write returns an appropriate error.) +Every successful read returns 0 bytes; thus a read can be used to check that the user is known and has a secret key. +Each write contains data of the following form: +.IP +.EX +.fi +.I oldhash +[ +.I newsecret +] +.EE +.PP +.I Oldhash +is the SHA1 hash +(see +.IR keyring-sha1 (2)) +of the user's existing secret, as 20 hexadecimal digits. +If the value of +.I oldhash +does not match that of the stored secret, the write returns an error and suitable diagnostic. +.I Oldhash +is optionally followed by a +.IR newsecret , +in clear text as a sequence of bytes (typically the secret as +.IR utf (6)), +separated from +.I oldhash +by a single space. +If the +.I oldhash +matches that of the secret currently stored, +.I newsecret +replaces it. +The write returns an error if +.I oldhash +does not match the stored value, or if something else goes wrong. +.PP +.I Keysrv +can be invoked via +.IR listen (1): +.IP +.EX +listen -t -A 'tcp!*!infkey' {auth/keysrv} +.EE +.PP +Normally that is done automatically when +starting an authentication service using +.B svc/auth +(see +.IR svc (8)). +.PP +.IR Passwd (1) +dials the service, authenticates, and mounts the resulting connection on +.BR /mnt/keysrv , +where it accesses the +.B secret +file to change the secret. +.SH FILES +.TF /mnt/keysrv +.TP +.B /mnt/keys +mount point for +.IR keyfs (4) +.TP +.B /mnt/keysrv +exported mount point for +.I keysrv +.SH SOURCE +.B /appl/cmd/auth/keysrv.b +.SH SEE ALSO +.IR listen (1), +.IR passwd (1), +.IR keyfs (4), +.IR logind (8) diff --git a/man/4/kfs b/man/4/kfs new file mode 100644 index 00000000..c52c1d3a --- /dev/null +++ b/man/4/kfs @@ -0,0 +1,175 @@ +.TH KFS 4 +.SH NAME +kfs \- disk file system +.SH SYNOPSIS +.BI "mount {disk/kfs" +.RB [ -r +[ +.BI -b " bsize" +] ] +.RB [ -c ] +.RB [ -A ] +.RB [ -P ] +.RB [ -R ] +.RB [ -W ] +[ +.BI -n " name" +] +.IB " file" "} " dir +.SH DESCRIPTION +.I Kfs +implements a hierarchical Inferno file system within an existing +.IR file , +which is typically a disk or flash memory partition. +It gives access to it through the Styx protocol on its standard input, +and the contents can be mounted directly on a given +.I dir +as shown above. +The file system format is the same as that used by the +.I kfs +command of Plan 9, except that the modification user ID is implemented. +.PP +The +.B -r +option causes the file system to be reset to an initially empty state +(`reamed'). +Permission checking is turned off, to allow any desired permissions and +file ownership to be set. +(In other words, the +.B -W +and +.B -P +options are also set by default.) +The file system block size is set to the +.IR bsize +given by the +.B -b +option +(default: 1024 bytes), +which must be a multiple of 512 and not greater than 16k bytes. +The block size is stored in the +.I file +and need not be given again. +The storage representation is always little-endian. +.PP +Otherwise, the file system is checked if required, unless the +.B -c +option is given. +.PP +The contents of the file system can be provided by using commands +such as +.IR mkdir (1), +.IR cp (1) +and +.IR rm (1) +in +.IR dir , +or built from a description using +.IR mkfs (8). +.PP +The mapping between user names and +internal IDs within the file system is established by the file +.BR adm/users +(within the file system itself) +as described by +.IR users (6), +which +.I kfs +reads when it starts. +If no such file exists, as for instance when the file system is initially empty, +.I kfs +uses a minimal set corresponding to the following +.IR users (6) +file: +.IP +.EX +-1:adm:adm: +0:none:adm: +9999:noworld:: +10000:sys:: +10001:upas:upas: +10002:bootes:bootes: +10006:inferno:: +.EE +.PP +Any +.IR users (6) +file used with +.I kfs +should include entries for at least +.BR adm , +.BR none , +and +.BR noworld +as above (although group membership can vary). +.PP +.I Kfs +can optionally serve a control file, for use by +.IR kfscmd (8). +If the +.B -n +option is given, +.I kfs +creates a channel +.BI /chan/kfs. name .cmd +and accepts commands on it from the user that started +.IR kfs . +.PP +Other options are: +.TP +.B -A +do not update access times; useful when running a file system in flash over +.IR ftl (3), +to avoid excessive wear +.TP +.B -P +suppress permission checking +.TP +.B -R +file system is read only +.TP +.B -W +allow +.B wstat +(see +.IR sys-stat (2) +or +.IR stat (5)) +to make arbitrary changes to user and group fields +.SH EXAMPLES +Create an empty file system +in the file +.BR kfs.file . +Because the file system will be no larger than the existing +file's size, and the file is assumed not to be a device file, use +.IR zeros (1) +to prepare a file with 2048 blocks of 1024 bytes each: +.IP +.EX +zeros 1024 2048 >kfs.file +mount -c {disk/kfs -r kfs.file} /n/local +.EE +.PP +The +.B -c +option to +.I mount +allows files to be created in +.BR /n/local . +.SH SOURCE +.B /appl/cmd/disk/kfs.b +.SH SEE ALSO +.IR dd (1), +.IR zeros (1), +.IR flash (3), +.IR ftl (3), +.IR logfs (3), +.IR sd (3), +.IR users (6), +.IR kfscmd (8), +.IR mkfs (8) +.SH BUGS +Because the file system format is the same as Plan 9's +.IR kfs , +this one also does not support file names longer than 27 bytes. +It likewise cannot cope with files bigger than 2ⁱ-1 bytes. diff --git a/man/4/lockfs b/man/4/lockfs new file mode 100644 index 00000000..8914f934 --- /dev/null +++ b/man/4/lockfs @@ -0,0 +1,89 @@ +.TH LOCKFS 4 +.SH NAME +lockfs \- exclusive access file server +.SH SYNOPSIS +.B lockfs +[ +.B -A +] [ +.B -a +.I alg +]... [ +.B -p +.I addr +] +.I dir +[ +.I mountpoint +] +.SH DESCRIPTION +.I Lockfs +acts as a filesystem layer above an existing namespace, +allowing multiple-reader, exclusive writer access to the +files therein. Opening a file served by +.I lockfs +obtains a lock on the file, or blocks until a lock can +be obtained. +.I Lockfs +serves a single-level directory that initially contains the +files in +.IR dir . +If the +.B -p +option is provided, +.I lockfs +will listen for incoming connections on +.IR addr , +authenticating them as required. +Each +.B -a +argument provides an acceptable +algorithm to run on the connection. +The list of all +.IR alg s +is passed to +.B server (see +.IR security-auth (2)). +If no +.B -a +arguments are given, +.B "-a none" +is assumed. +If the +.B -A +option is given, then no authentication +will be performed. +.PP +If the +.B -p +option is not given, the lockfs file system +will be mounted on +.IR mountpoint , +or +.I dir +if +.I mountpoint +is not given. +.SH EXAMPLE +Run a lock server guarding access to +.BR /lib/datafiles : +.IP +.EX +lockfs -p 'tcp!*!32454' /lib/datafiles +.EE +.PP +Mount the above server (where +.I locksrv +was originally run on a server named +.IR machine . +.IP +.EX +mount -c tcp!\fImachine\fP!32454 /n/remote +.EE +.SH SOURCE +.B /appl/cmd/lockfs.b +.SH BUGS +There's no way to break a lock held by a +malingering process. +.PP +Should probably support multi-level directories. diff --git a/man/4/logfile b/man/4/logfile new file mode 100644 index 00000000..ee05f38b --- /dev/null +++ b/man/4/logfile @@ -0,0 +1,45 @@ +.TH LOGFILE 4 +.SH NAME +logfile \- memory-based append-only circular storage buffer +.SH SYNOPSIS +.B logfile +.RB [ \-\fIsize\fP ] +.I \fIfile\fP +.SH DESCRIPTION +.I Logfile +creates a name at +.I file +(the containing directory must already exist). +Each write to +.I file +appends the written data up to a maximum of +.I size +bytes; subsequent writes erase the existing +data in a circular fashion. A read from +.I file +will return any currently stored data, if any; +if there is none, then it will block until more +data becomes available. +Multiple readers will receive the data independently +of one another. If a writing process is consistently +producing data faster than a reading process, then +the data read will have some bytes elided; a write +is never blocked. +.SH SOURCE +.B /appl/cmd/logfile.b +.SH SEE ALSO +.IR wm-logwindow (1), +.IR sys-file2chan (2) +.SH BUGS +Restrictions on +.IR sys-file2chan (2) +mean that the +.I logfile +process will not terminate automatically +when its file is removed or unmounted. +.PP +There is no indication to a reader of any +missing data. +.PP +It is not possible to do a non-blocking +read of the log file. diff --git a/man/4/memfs b/man/4/memfs new file mode 100644 index 00000000..7394fa53 --- /dev/null +++ b/man/4/memfs @@ -0,0 +1,62 @@ +.TH MEMFS 4 +.SH NAME +memfs \- mount a heap based filesystem +.SH SYNOPSIS +.B memfs +.RB [ \-s ] +.RB [ \-rab ] +.RB [ \-m +.IR size ] +.RI [ mountpoint ] +.SH DESCRIPTION +.I Memfs +mounts a newly created heap-based filesystem +on the given +.I mountpoint +directory (default +.BR /tmp ). +.PP +The filesystem is entirely maintained in memory, no external storage is used. +File data is allocated in 512 byte blocks. +If a maximum +.I size +is specified, the actual maximum is rounded down to the nearest +whole number of blocks: +.IP +.EX +actualsize := (size / 512) * 512; +.EE +.PP +The root of the filesystem is owned by the user who invoked memfs and +is created with Read, Write and Execute permissions for the owner and Read and Execute +permissions for everyone else (8r755). +.PP +.SH OPTIONS +.TP +.B \-s +Serve styx on file descriptor 0. +The +.I mountpoint +and other mount options are ignored. +.TP +.B \-r +The default option. +The old +.I mountpoint +directory becomes a union directory consisting of just the root of the new filesystem. +.TP +.B \-a +Add the root of the new filesystem to the end of the union directory +represented by the +.I mountpoint +directory. +.TP +.B \-b +Add the root of the new filesystem to the beginning of the union directory +represented by the +.I mountpoint +directory. +.SH SOURCE +.B /appl/cmd/memfs.b +.SH SEE ALSO +.IR ramfile (4) diff --git a/man/4/mntgen b/man/4/mntgen new file mode 100644 index 00000000..934926f1 --- /dev/null +++ b/man/4/mntgen @@ -0,0 +1,30 @@ +.TH MNTGEN 4 +.SH NAME +mntgen \- dynamically generate mount points +.SH SYNOPSIS +.BI "mount {mntgen} " dir +.SH DESCRIPTION +.I Mntgen +serves a Styx connection on its standard input, providing a name space containing a +single directory that is initially empty, but in which a subdirectory name appears when +is first referenced, and remains only as long as it is needed (referenced). +.I Mntgen +is typically mounted on a directory +.I dir +using +.I mount +(see +.IR bind (1)) +as above. +.I Dir +is commonly +.B /n +or +.BR /mnt , +to generate mount points on demand for file systems or services. +.SH SOURCE +.B /appl/cmd/mntgen.b +.SH SEE ALSO +.IR intro (1), +.IR bind (1), +.IR intro (5) diff --git a/man/4/namespace b/man/4/namespace new file mode 100644 index 00000000..727b0adf --- /dev/null +++ b/man/4/namespace @@ -0,0 +1,332 @@ +.TH NAMESPACE 4 +.SH NAME +namespace \- structure of conventional Inferno name space +.SH SYNOPSIS +none +.SH DESCRIPTION +The list below gives an overview of the Inferno distribution +file tree, organised into related categories. +.TF /appl/cmd +.TP +.B / +The root directory. To programs running outside Inferno, +this corresponds to the directory in which Inferno has been +installed (e.g. +.B C:\einferno +under Windows). +.SS Mount points +The following are all placeholders for filesystems +that are mounted when Inferno is running. They +contain no data files. Although an Inferno namespace +is a dynamic entity, and devices can be mounted anywhere +therein, many programs assume that devices have been +mounted in the standard places, as suggested by the skeleton +directories listed below. +.TF /appl/cmd +.TP +.B /dev +The standard mount point +for devices (e.g. +.IR cons (3)) +.TP +.B /env +The standard mount point for the +.IR env (3) +device. +.TP +.B /mnt +A directory containing mount points for applications. +.TP +.B /chan +An empty directory, used for holding +files created with +.IR sys-file2chan (2). +.TP +.B /net +The standard mount point directory for network interfaces. +.TP +.B /n +A directory containing mount points for file trees on local devices or imported from +remote systems. +.TP +.B /prog +An empty directory, the mount point for the +.IR prog (3) +device. +.TP +.B /nvfs +An empty directory, the mount point for a non-volatile RAM +filesystem on devices that have one. +.TP +.B /tmp +Mount point for private +directory of temporary files (eg, +.BI /usr/ user /tmp\c +). +.TP +.B /mail +Conventional place to mount mailboxes. +.SS Limbo applications +.TF /appl/cmd +.TP +.B /dis +Dis executables (commands) +.TP +.B /dis/lib +Dis libraries +.TP +.B /dis/wm +Dis commands that run under +.IR wm (1). +.TP +.B /man +Manual pages. +.TP +.B /doc +Documentation other than manual pages. +.TP +.B /appl +Source to Limbo applications. +.TP +.B /appl/cmd +Source to the commands in +.BR /dis +(as documented in Section 1). +.TP +.B /appl/wm +Source to the commands in +.B /dis/wm +.TP +.B /appl/lib +Source to the modules in +.B /dis/lib +(as documented in Section 2). +.TP +.B /module +Limbo module declarations +.SS Supporting data +.TF /appl/cmd +.TP +.B /acme +Programs and guide files specific to +.IR acme (1). +.TP +.B /fonts +Font definitions +.TP +.B /locale +Timezone and locale information +.TP +.B /icons +Contains +.IR image (6) +files used by programs. +.TP +.B /icons/tk +Default directory searched by tk's +.B -bitmap +option (see +.IR options (9)). +.TP +.B /lib +Static program-specific data. +.TP +.B /lib/ndb +Network configuration files +used by +.IR cs (8), +.IR dns (8) +and others. +.SS Administration +.TF /appl/cmd +.TP +.B /keydb +Storage of secrets and certificates on signers (authentication servers). +.TP +.B /services +A jungle of program-specific configuration files. +.SS Platform specific +.TF /appl/cmd +.TP +.BI / Platform +Binaries specific to +.IR Platform . +Current platforms include +.B Inferno +(native binaries), +.BR FreeBSD , +.BR Hp , +.BR Irix , +.BR Linux , +.BR Nt , +.BR Plan9 , +.B Solaris +and +.BR Unixware . +.TP +.BI / Platform / arch /bin +.TP +.BI / Platform / arch /lib +.TP +.BI / Platform / arch /include +.I Platform +specific binaries, libraries and include files +respectively. +.I Arch +is the architecture type, as defined +in +.IR 2c (10.1) +and held in the +.B $objtype +environment variable. +.TP +.B /usr +A directory containing user directories. +.SS Inferno source code +.TF /libmemlayerxx +.TP +.B /emu +Directory containing source specific to +.IR emu (1). +.TP +.B /emu/port +Cross-platform source for +.IR emu (1). +.BI /emu/ Platform +.IR Platform -specific +source for +.IR emu (1). +.TP +.B /libkfs +The emu version of +.IR kfs (3). +.TP +.B /libbio +.TP +.B /libregexp +Source to libraries used by hosted commands. +.TP +.B /lib9 +Source to the Plan 9 emulation library, used by +emu and the hosted commands. +.TP +.B /libmemdraw +.TP +.B /libmemlayer +.TP +.B /libprefab +.TP +.B /libkern +.TP +.B /libkeyring +.TP +.B /libdraw +.TP +.B /libinterp +.TP +.B /libtk +Inferno source used by both native and hosted versions of +Inferno. +.TP +.B /asm +.TP +.B /limbo +Source to the two hosted Inferno commands of +the same name. +.TP +.B /utils +Source to hosted utilities run from +.IR emu (1) +via the +.IR cmd (3) +interface. +.TP +.B /tools +A directory containing source directories +for hosted tools used in building Inferno +(e.g. +.IR mk (10.1)). +.TP +.B /os +A directory holding source directories for the native versions of Inferno. +.TP +.B /os/init +Limbo source for platform-specific initialisation procedures. +.TP +.B /os/port +Portable native kernel source. +.TP +.BI /os/ arch +.IR Arch -specific +native kernel source. +.TP +.B /os/kfs +The native kernel version of +.IR kfs (3). +.SS "Minimal name space" +The above is all very well on a system with lots of storage, +but what is actually necessary for the running of Inferno? +The following gives a quick summary of the structure that +must be provided for Inferno to function correctly. +.TF /appl/cmd +.TP +.B /dis +This must contain Dis modules for all the applications +you plan to run, and the modules they depend on. +.IR Disdep (1) +can be useful when trying to determine this set. +.TP +.B /dev +.TP +.B /env +.TP +.B /chan +.TP +.B /net +.TP +.B /prog +.TP +.B /tmp +All empty unwritable directories, place holders for mounted services and +applications. +Often these are provided by the built-in +.IR root (3). +.TP +.B /mnt +A directory containing mount points for applications. +.TP +.B /n +A directory containing mount points for remote file systems. +.SS "Files needed to run as a server" +.TF /appl/cmd +.TP +.B /keydb/keys +See +.IR keyfs (4), +.IR logind (8) +and +.IR signer (8). +.TP +.B /keydb/signerkey +See +.IR createsignerkey (8) +and +.IR logind (8). +.SS "Files needed to run the window manager" +.TF /appl/cmd +.TP +.B /fonts +At least one font must be provided - a default font for Tk +to use. +.TP +.B /icons/tk +This should contain icons used by applications that run within Tk. +.TP +.BI /user/ user +At least one user directory must exist if +.IR logon (1) +is to function correctly. +.SH SEE ALSO +.IR intro (1), +.IR root (3), +.IR namespace (6) diff --git a/man/4/palmsrv b/man/4/palmsrv new file mode 100644 index 00000000..d5718771 --- /dev/null +++ b/man/4/palmsrv @@ -0,0 +1,49 @@ +.TH PALMSRV 4 +.SH NAME +palmsrv \- packet link to Palm device on serial connection +.SH SYNOPSIS +.B palm/palmsrv +[ +.B -D +] [ +.BI -d " device" +] [ +.BI -s " speed" +] +.SH DESCRIPTION +.I Palmsrv +serves packet link connections to a Palm device connected on the given +.I device +(default: +.BR "/dev/eia0" ) +at the given +.I speed +(default: +57600 baud). +Client applications open +.B /chan/palmsrv +to obtain a connection. +Each write must contain the data portion of a single Packet Assembly-Disassembly Protocol message +containing a Desklink protocol request. +If the device rejects the request, the write returns a diagnostic; otherwise, +a subsequent read will retrieve the reply. +.PP +The server can be shut down by writing the text +.B exit +to the file +.BR /chan/palmsrv : +.IP +.EX +echo -n exit >/chan/palmsrv +.EE +.PP +.SH FILES +.B /chan/palmsrv +.SH SOURCE +.B /appl/cmd/palm/palmsrv.b +.SH SEE ALSO +.IR palmfile (2) +.SH BUGS +It does not yet support USB. +.br +It does not tickle the Palm when there are long delays. diff --git a/man/4/ramfile b/man/4/ramfile new file mode 100644 index 00000000..415c3094 --- /dev/null +++ b/man/4/ramfile @@ -0,0 +1,63 @@ +.TH RAMFILE 4 +.SH NAME +ramfile \- synthesise file +.SH SYNOPSIS +.B ramfile +.I file +[ +.I data +] +.SH DESCRIPTION +.I Ramfile +puts a virtual file in the name space at +.IR file , +and services file requests on it. +Data written to the file is stored in +.IR ramfile 's +memory; read requests return the previously stored data. +If the optional +.I data +argument is provided, the file will initially contain that text. +The parent directory of +.I file +must exist; +.I ramfile +creates a union mount on that directory, and if +.I file +previously existed, the synthesised file will hide it. +.PP +.I Ramfile +uses +.IR sys-file2chan (2), +which simplifies implementation but prevents it from knowing +when the file has been truncated. +Instead, it truncates the file on any write to the start of the file +(offset 0), +allowing +.IR cp (1) +to copy in new contents, and +text editors to edit it. +Indeed, the file will be usable by all applications that do +not rely on updating parts of the file in place, or if they do, +do not update the start of the file. +.SH SOURCE +.B /appl/cmd/ramfile.b +.SH SEE ALSO +.IR bind (1), +.IR sys-file2chan (2), +.IR srv (3), +.IR memfs (4) +.SH BUGS +.I Ramfile +cannot tell when the +.I path +has been unmounted; +the only option is to +.IR kill (1) +it. +.br +The +.I file +always appears to have zero length to +.IR sys-stat (2), +which prevents loading a Dis file from it. diff --git a/man/4/registry b/man/4/registry new file mode 100644 index 00000000..c952d3d6 --- /dev/null +++ b/man/4/registry @@ -0,0 +1,196 @@ +.TH REGISTRY 4 +.SH NAME +registry, regquery \- registration of services dynamically +.SH SYNOPSIS +.B ndb/registry +[ +.BI -f " dbfile" +] +.PP +.B ndb/regquery +[ +.BI -m " mntpt" +] +[ +.B -n +] +[ +.I "attr value" +] ... +.SH DESCRIPTION +.I Registry +is a file server that +provides registration and location of services by their attributes +where services come and go. +It was originally intended to register Grid resources +but has much wider use. +.I Registry +serves Styx on its standard input. +That can be mounted in the local name space (see below for an example), +or served over a connection +(eg, via +.IR listen (1)). +The conventional local mount point is +.BR /mnt/registry , +which is where +.IR registries (2) +expects to find the local registry by default. +There can, however, be any number of registries active, +each supporting a different group of users and services, +in different authentication domains. +.PP +.I Registry +serves a one-level directory containing a few control files +and one file per registered service. +All the files are text files with similar format: +zero or more lines of one or more words, separated by white space (blank or tab). +A word can be quoted, using single quotes in the style of +.IR sh (1), +allowing it to contain white space +or represent the empty string +.BR \&'' . +Within a quoted word, a single quote character is represented by two adjacent ones. +(In programs, use +.B String->quoted +from +.IR string (2), +or more simply the +.B %q +string format of +.IR sys-print (2) +to quote strings appropriately.) +.PP +The control files are: +.TF index +.PD +.TP +.B new +A text file that is opened and written to register a new service. +Opening +.B new +returns a file descriptor to a new but anonymous service file. +It must be written to set its name and initial description. +The first write contains one or more words: +.RS +.IP +.IR svcname " [" " attr value " ] ..." +.PP +The first word, +.IR svcname , +is the proposed service name. +The write returns an error if the name duplicates any existing name. +Otherwise, a new file +.I svcname +will appear in the directory. +The optional attribute value pairs form the initial service description. +The service is removed from the register by default when the file is closed. +To advertise a service without having to hold open a file descriptor, include an +.I attr +named +.B persist +with non-zero +.IR value ; +the service will then remain registered until explicitly removed (see below). +.RE +.TP +.B index +A read-only text file containing a list of all the currently-registered services, one per line. +Each line contains a sequence of words. +The first word is the service name and the remaining ones are paired: attribute name then value. +.TP +.B find +A text file which should be opened for reading and writing. +Each write provides a set of attribute/value pairs that acts as a filter, selecting only those +services that possess all the given attributes with the given values; +the value +.B \&"*" +matches any value. +Subsequent reads return a list of services, in the same format +as +.BR index , +but listing only the selected services. +The selection is made from those available at the time of the write. +There is a separate filter for each open instance of +.BR find , +so that several processes can set different filters simultaneously. +(Note that after the write, the file offset must be set to zero using +.IR sys-seek (2) +before reading.) +.PP +A service file created by +.B new +may be read by anyone, but may be written only by its owner. +Each write must contain a set of attribute/value pairs, formatted as above, which adds new attributes to the service +description and changes the value of +existing attributes. +The file remains until the service is struck off the register. +The owner of a service can remove its registration at any time by removing the corresponding +service file (eg, using +.IR rm (1) +or +.IR sys-remove (2)). +.PP +Typically, most services register themselves dynamically, perhaps using their locations (eg, network address) +as their service names. +.RI ( Registry +itself does not interpret the name.) +The +.B -f +option causes +.I registry +to load initially a set of static service descriptions from +.IR dbfile , +which is in +.IR attrdb (6) +format. +The database entry for each service contains the pair +.BI service= svcname, +causing +.I registry +to make an entry for the given +.I svcname +with attribute/value pairs initialised from the rest of that database entry. +For example: +.IP +.EX +service=net!click!1234 + description='snapshot service' auth=none +.EE +.PP +Static entries are regarded as persistent but can be removed explicitly by the registry owner. +.PP +.I Regquery +looks for services in the registry mounted at +.I mntpt +(default: +.BR /mnt/registry ) +that match all the given attribute/value pairs. +It prints the resulting list of services, one per line. +If the +.B -n +option is given, +.I regquery +prints only the service name(s); otherwise it prints the service description as well. +If no attributes are given on the command line, +.I regquery +prompts for successive queries, one per line, and prints each result. +.SH EXAMPLE +Start a registry that appears at the standard location for local registries, +.BR /mnt/registry : +.IP +.EX +mount -A ${pipe to ndb/register} /mnt/registry +.EE +.PP +Make that registry available to the network on authenticated connections: +.IP +.EX +listen -v 'tcp!*!registry' {export /mnt/registry&} +.EE +.SH SOURCE +.B /appl/cmd/ndb/registry.b +.SH SEE ALSO +.IR attrdb (2), +.IR registries (2) +.SH BUGS +It is not currently possible to have two values with the same attribute name in the same service description. diff --git a/man/4/spree b/man/4/spree new file mode 100644 index 00000000..f4541e1d --- /dev/null +++ b/man/4/spree @@ -0,0 +1,195 @@ +.TH SPREE 4 +.SH NAME +spree \- distributed interactive sessions. +.SH SYNOPSIS +.B mount {spree/spree} /n/remote +.PP +.B /n/remote/name +.br +.BI /n/remote/ n +.br +.BI /n/remote/ n /ctl +.SH DESCRIPTION +.B Spree +serves a file system that allows clients to interact +through various types of +.I engine +(see +.IR spree (2) +for an explanation of engines). +It serves styx messages through file descriptor 0; +thus it can be mounted directly with +.IR mount (1), +or made available across the network +with +.I styxlisten +(see +.IR listen (1)). +.PP +Spree serves a name-space consisting of a directory +for each clique that is currently active, and +a file, +.BR name , +that holds the authenticated name of the user that has +mounted the spree namespace. +A clique's directory holds at least one file, +.BR ctl ; +if a client opens this file, it can write to it +communicate with the clique's engine, and read from +it to find updates to the state of the clique. +Messages written to the file are formed as text +and the write yields an error if there is an error +executing the command. +The first message written to the file is the +initial request to join the clique; conventionally it +is the string +.BR join , +but some engines accept other kinds of message +(e.g. +.BR watch ). +If the initial request succeeds, the client will be +informed of the current state of the clique by means +of update messages read from the same file. +Reading from the file will block until an update +is available, whereupon the read request will return +as many updates are available, separated by newline characters. +If there are more updates available than can fit +in the read request, the last two bytes of the buffer +read will be a newline character and an asterisk +.RB ( * ) +respectively, indicating that there are more updates +to come. +.PP +When +.I spree +is first started, it creates one clique, a ``lobby'' +(see +.IR spree-lobby (4)) +that allows other cliques to be created; this +is named +.BR 0 ). +.PP +A client cannot join a particular clique +more than once. +.PP +A zero-length write to the +.B ctl +file causes any reads +of that file from the same file descriptor to yield +EOF (no bytes). +This is necessary to force a hangup under +systems such as Windows, where it is not possible +to interrupt a kproc blocked on a network read. +.PP +The update messages generated by +.I spree +are as follows: +.RS +.TP +.BI create " objid parentid visibility objtype" +Create an object, identified by +.IR objid , +at the end of +.IR parentid 's +children +.RI ( parentid +is +.B -1 +for the root object). +.I Visibility +is non-zero if the object's children are visible +to the member reading the update. +.I Objtype +is the object's type (engine dependent). +.TP +.BI tx " srcid dstid start end index" +Transfer objects from +.I srcid +to +.IR dstid. +Take the objects from the range +.RI [ start ,\ end ) +in the children of +.IR srcid , +and insert them just before +.I index +in +.IR dstid . +When objects are transferred +to an object that conceals its children, +and the object is itself visible, +the objects will first be transferred to the +destination and then deleted; objects transferred +out of such an object will first be created and +.I then +transferred to their destination. +This enables a client to maintain some knowledge +of where an object has been transferred to, even +if the object is no longer visible, and means +that a client is unable to keep track of objects +that are concealed from it. +.TP +.BI del " parentid start end " "" objid\fR... +Delete the range +.RI [ start ,\ end ) +of children from the object identified by +.IR parentid . +.I Spree +guarantees that those objects will themselves +not have any children. +The list of +.IR objid s +gives the actual identifiers of the objects deleted, +for the benefit of clients that do not wish to keep lists of objects' children. +.TP +.BI set " objid attr val" +Set the attribute named +.I attr +on object +.I objid +to +.IR val . +.TP +.BI vis " objid visibility" +The visibility of object to the reading member +.I objid +has changed to +.I visibility +(non-zero if visible). +.TP +.I action +Game engines can generate arbitrary messages +of their own devising; such messages are specific +to particular engine types. +.PP +Note that a given client does not have to interpret +all the above messages \- different client types +have their own conventions. The +.B card +client type uses most of the above functionality, +for example, whereas a client for the +.B chat +engine listed in +.IR spree (2) +can get away with interpreting only one message, the custom action +.BR chat . +.PP +Writes to the opened clique file +are interpreted as clique actions by +the clique that has been loaded, and acted on accordingly. +Invalid actions will draw a write error. +.RE +.SH EXAMPLE +The simplest client! +.PP +.EX +mount tcp!somehost.com!3242 /n/remote +{ + echo create chat >[1=0] + cat & + cat >[1=0] < /dev/cons +} <> /n/remote/new +.SH SOURCE +.B /appl/cmd/cliques/spree.b +.SH SEE ALSO +.IR spree (2) diff --git a/man/4/tarfs b/man/4/tarfs new file mode 100644 index 00000000..7025379b --- /dev/null +++ b/man/4/tarfs @@ -0,0 +1,40 @@ +.TH TARFS 4 +.SH NAME +tarfs \- mount tar archive +.SH SYNOPSIS +.B tarfs +[ +.B -ab +] +.I tarfile +.I mountpt +.SH DESCRIPTION +.I Tarfs +makes the contents of the directories and files archived in the given Unix/POSIX +.I tar +archive +.I tarfile +visible in the name space under +.IR mountpt . +They can then be accessed in an obvious way by other commands +such as +.IR ls (1) +and +.IR cp (1). +Only read access is supported. +User and group names are simply the numeric user and group IDs in the file. +The +.B -a +and +.B -b +options cause the +.IR tarfile 's +name space to be placed after or before the current contents of +.IR mountpt ; +the default is to replace that directory's contents. +.SH SOURCE +.B /appl/cmd/tarfs.b +.SH SEE ALSO +.IR gettar (1), +.IR archfs (4), +.IR intro (5) |