OpenSource Headlines

Use embedded Linux and open-source software to build a networked audio appliance.

Benchmarking ZFS On FreeBSD vs. EXT4 & Btrfs On Linux

ZFS is often looked upon as an advanced, superior file-system and one of the strong points of the Solaris/OpenSolaris platform while most feel that only recently has Linux been able to catch-up on the file-system front with EXT4 and the still-experimental Btrfs.

openmamba 20100728

It runs on computers based on the 32-bit Intel x86 architecture, or on 64-bit AMD processors in 32-bit mode.

Even SAP is using more open source

By Source Seeker on Wed, 07/28/10 - 5:55pm. Yesterday SAP took another step into the open source world by signing on to use the Black Duck Suite .

Why WikiLeaks Is The Pirate Bay of Political Intelligence

WikiLeaks is currently in the news because its Afghan War logs comprise one of the largest and most controversial intelligence leaks to date.

Convirture goes open core with 2.0 virt tools

Convirture has unveiled a management tool for open source hypervisors. It's been clear from the beginning of the server virtualization wave that eventually the hypervisor would become commoditized and that the real action, in terms of functionality as well as in money, would come with the management tools that wrap around the hypervisor and make it ...

proxy servers

May 4, 2009 ... As an alternative to downloading the files, the HCPM/HAI Synthesis Cost Proxy Model may be obtained from the FCC's duplicating contractor, ... http://www.fcc.gov/ccb/apd/hcpm/ Patent Database Notices and Status The database servers are now capable of processing approximately 300 simultaneous searches.

Open source installer offered for Plug Computer

Marvell announced the availability of an open source installer, simplifying software deployment on its Linux-based Plug Computer reference design.

Google patches Chrome, sidesteps Windows kernel bug

July 28, 2010, 09:59 AM - Computerworld - Google on Monday patched five vulnerabilities in Chrome by issuing a new "stable" build of the browser.

Fast Easy Web Hosting

Your Say About Movies

Cigars Review

Man Pages

File Formats

Browse in :

All > Documents > Man Pages > File Formats (375)

All A B C D E F G H I J K L M N O P Q R S T U V W X Y Z Other

acct

NAME

acct - execution accounting file

SYNOPSIS

#include <sys/acct.h>

DESCRIPTION

If the kernel was compiled with the process accounting option enabled, the system call

: acct("/somewhere/accountingfile");

will start the process accounting. Each time a process terminates a record for this process is appended to the accounting file. The accounting structure struct acct is also described in the file /usr/include/linux/acct.h.

acl

NAME

acl - Access Control Lists

DESCRIPTION

This manual page describes POSIX Access Control Lists, which are used to define more fine-grained discretionary access rights for files and directories.

ACL TYPES

Every object can be thought of as having associated with it an ACL that governs the discretionary access to that object; this ACL is referred to as an access ACL. In addition, a directory may have an associated ACL that governs the initial access ACL for objects created within that directory; this ACL is referred to as a default ACL.

ACL ENTRIES

An ACL consists of a set of ACL entries. An ACL entry specifies the access permissions on the associated object for an individual user or a group of users as a combination of read, write and search/execute permissions.

An ACL entry contains an entry tag type, an optional entry tag qualifier, and a set of permissions. We use the term qualifier to denote the entry tag qualifier of an ACL entry.

The qualifier denotes the identifier of a user or a group, for entries with tag types of ACL_USER or ACL_GROUP, respectively. Entries with tag types other than ACL_USER or ACL_GROUP have no defined qualifiers.

The following entry tag types are defined:

ACL_USER_OBJ: The ACL_USER_OBJ entry denotes access rights for the file owner.
ACL_USER: ACL_USER entries denote access rights for users identified by the entry`s qualifier.
ACL_GROUP_OBJ: The ACL_GROUP_OBJ entry denotes access rights for the file group.
ACL_GROUP: ACL_USER entries denote access rights for groups identified by the entry`s qualifier.
ACL_MASK: The ACL_MASK entry denotes the maximum access rights that can be granted by entries of type ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP.
ACL_OTHER: The ACL_OTHER entry denotes access rights for processes that do not match any other entry in the ACL.

When an access check is performed, the ACL_USER_OBJ and ACL_USER entries are tested against the effective user ID. The effective group ID, as well as all supplementary group IDs are tested against the ACL_GROUP_OBJ and ACL_GROUP entries.

VALID ACLs A valid ACL contains exactly one entry with each of the ACL_USER_OBJ,

ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries with ACL_USER and ACL_GROUP tag types may appear zero or more times in an ACL. An ACL that contains entries of ACL_USER or ACL_GROUP tag types must contain exactly one entry of the ACL_MASK tag type. If an ACL contains no entries of ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is optional.

All user ID qualifiers must be unique among all entries of ACL_USER tag type, and all group IDs must be unique among all entries of ACL_GROUP tag type.

The Fn acl_get_file function returns an ACL with zero ACL entries as the default ACL of a directory, if the directory is not associated with a default ACL. The Fn acl_set_file function also accepts an ACL with zero ACL entries as a valid default ACL for directories, denoting that the directory shall not be associated with a default ACL. This is equivalent to using the Fn acl_delete_def_file function.

CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS

The permissions defined by ACLs are a superset of the permissions specified by the file permission bits. The permissions defined for the file owner correspond to the permissions of the ACL_USER_OBJ entry. The permissions defined for the file group correspond to the permissions of the ACL_GROUP_OBJ entry, if the ACL has no ACL_MASK entry. If the ACL has an ACL_MASK entry, then the permissions defined for the file group correspond to the permissions of the ACL_MASK entry. The permissions defined for the other class correspond to the permissions of the ACL_OTHER_OBJ entry.

Modification of the file permission bits results in the modification of the permissions in the associated ACL entries. Modification of the permissions in the ACL entries results in the modification of the file permission bits.

OBJECT CREATION AND DEFAULT ACLs The access ACL of a file object is initialized when the object is

created with any of the Fn creat , Fn mkdir , Fn mknod , Fn mkfifo , or Fn open functions. If a default ACL is associated with a directory, the mode parameter to the functions creating file objects and the default ACL of the directory are used to determine the ACL of the new object:

The new object inherits the default ACL of the containing directory as its access ACL.
The access ACL entries corresponding to the file permission bits are modified so that they contain no permissions that are not contained in the permissions specified by the mode parameter.

If no default ACL is associated with a directory, the mode parameter to the functions creating file objects and the file creation mask (see umask(2)) are used to determine the ACL of the new object:

The new object is assigned an access ACL containing entries of tag types ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER. The permissions of these entries are set to the permissions specified by the file creation mask.
The access ACL entries corresponding to the file permission bits are modified so that they contain no permissions that are not contained in the permissions specified by the mode parameter.

ACCESS CHECK ALGORITHM

A process may request read, write, or execute/search access to a file object protected by an ACL. The access check algorithm determines whether access to the object will be granted.

If the effective user ID of the process matches the user ID of the file object owner, then
if the ACL_USER_OBJ entry contains the requested permissions, access is granted,
else access is denied.
else if the effective user ID of the process matches the qualifier of any entry of type ACL_USER, then
if the matching ACL_USER entry and the ACL_MASK entry contain the requested permissions, access is granted,
else access is denied.
else if the effective group ID or any of the supplementary group IDs of the process match the file group or the qualifier of any entry of type ACL_GROUP, then
if the ACL contains an ACL_MASK entry, then if the ACL_MASK entry and any of the matching ACL_GROUP_OBJ or ACL_GROUP entries contain the requested permissions, access is granted,
else access is denied.
else (note that there can be no ACL_GROUP entries without an ACL_MASK entry) if the ACL_GROUP_OBJ entry contains the requested permissions, access is granted,
else access is denied.
else if the ACL_OTHER entry contains the requested permissions, access is granted.
else access is denied.

ACL TEXT FORMS

A long and a short text form for representing ACLs is defined. In both forms, ACL entries are represented as three colon separated fields: an ACL entry tag type, an ACL entry qualifier, and the discretionary access permissions. The first field contains one of the following entry tag type keywords:

user: A user ACL entry specifies the access granted to either the file owner (entry tag type ACL_USER_OBJ) or a specified user (entry tag type ACL_USER).
group: A group ACL entry specifies the access granted to either the file group (entry tag type ACL_GROUP_OBJ) or a specified group (entry tag type ACL_GROUP).
mask: A mask ACL entry specifies the maximum access which can be granted by any ACL entry except the user entry for the file owner and the other entry (entry tag type ACL_MASK).
other: An other ACL entry specifies the access granted to any process that does not match any user or group ACL entries (entry tag type ACL_OTHER).

The second field contains the user or group identifier of the user or group associated with the ACL entry for entries of entry tag type ACL_USER or ACL_GROUP, and is empty for all other entries. A user identifier can be a user name or a user ID number in decimal form. A group identifier can be a group name or a group ID number in decimal form.

The third field contains the discretionary access permissions. The read, write and search/execute permissions are represented by the r w and x characters, in this order. Each of these characters is replaced by the - character to denote that a permission is absent in the ACL entry. When converting from the text form to the internal representation, permissions that are absent need not be specified.

White space is permitted at the beginning and end of each ACL entry, and immediately before and after a field separator (the colon character).

LONG TEXT FORM

The long text form contains one ACL entry per line. In addition, a number sign ( # may start a comment that extends until the end of the line. If an ACL_USER, ACL_GROUP_OBJ or ACL_GROUP ACL entry contains permissions that are not also contained in the ACL_MASK entry, the entry is followed by a number sign, the string lqeffective:rq, and the effective access permissions defined by that entry. This is an example of the long text form:

user::rw- user:lisa:rw- #effective:r-- group::r-- group:toolies:rw- #effective:r-- mask::r-- other::r--

SHORT TEXT FORM

The short text form is a sequence of ACL entries separated by commas, and is used for input. Comments are not supported. Entry tag type keywords may either appear in their full unabbreviated form, or in their single letter abbreviated form. The abbreviation for user is u the abbreviation for group is g the abbreviation for mask is m and the abbreviation for other is o The permissions may contain at most one each of the following characters in any order: r w x These are examples of the short text form:

u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r-- g:toolies:rw,u:lisa:rw,u::wr,g::r,o::r,m::r

RATIONALE

IEEE 1003.1e draft 17 defines Access Control Lists that include entries of tag type ACL_MASK, and defines a mapping between file permission bits that is not constant. The standard working group defined this relatively complex interface in order to ensure that applications that are compliant with IEEE 1003.1 (lqPOSIX.1rq) will still function as expected on systems with ACLs. The IEEE 1003.1e draft 17 contains the rationale for choosing this interface in section B.23.

CHANGES TO THE FILE UTILITIES

On a system that supports ACLs, the file utilities ls(1), cp(1), and mv(1) change their behavior in the following way:

For files that have a default ACL or an access ACL that contains more than the three required ACL entries, the ls(1) utility in the long form produced by ls -l displays a plus sign ( + after the permission string.
If the -p flag is specified, the cp(1) utility also preserves ACLs. If this is not possible, a warning is produced.
The mv(1) utility always preserves ACLs. If this is not possible, a warning is produced.

The effect of the chmod(1) utility, and of the chmod(2) system call, on the access ACL is described in Sx CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS .

STANDARDS

The IEEE 1003.1e draft 17 (lqPOSIX.1erq) document describes several security extensions to the IEEE 1003.1 standard. While the work on 1003.1e has been abandoned, many UNIX style systems implement parts of POSIX.1e draft 17, or of earlier drafts.

Linux Access Control Lists implement the full set of functions and utilities defined for Access Control Lists in POSIX.1e, and several extensions. The implementation is fully compliant with POSIX.1e draft 17; extensions are marked as such. The Access Control List manipulation functions are defined in the ACL library (libacl, -lacl). The POSIX compliant interfaces are declared in the <sys/acl.h> header. Linux-specific extensions to these functions are declared in the <acl/libacl.h> header.

afpd.conf

NAME

afpd.conf - Configuration file used by afpd(8) to determine the setup of its file sharing services

DESCRIPTION

/etc/atalk//afpd.conf is the configuration file used by afpd to determine the behavior and configuration of the different virtual file servers that it provides.

Any line not prefixed with # is interpreted. The configuration lines are composed like:

server name [ options ]

If a - is used instead of a server name, the default server is specified. Server names must be quoted if they contain spaces.

The path name must be a fully qualified path name, or a path name using either the ~ shell shorthand or any of the substitution variables, which are listed below.

The possible options and their meanings are:

AppleVolumes Files

-defaultvol [path]

Specifies path to AppleVolumes.default file (default is /etc/atalk//AppleVolumes.default).

-nlspath [path]

Specifies the path to the code pages (default is /etc/atalk//nls).

-systemvol [path]

Specifies path to AppleVolumes.system file (default is /etc/atalk//AppleVolumes.system).

-[no]uservol

Enables or disables reading of the users` individual volumes file entirely.

-[no]uservolfirst

Enables or disables reading of the users` individual volumes file before processing the global AppleVolumes.default file.

Authentication Methods

-uamlist [uams list]

Comma separated list of UAMs. (The default is uams_guest.so,uams_passwd.so,uams_dhx_passwd.so). The most commonly used UAMs are:

uams_dhx_passwd.so or uams_dhx_pam.so - allows logins using Diffie-Hellman eXchange (DHX)

uams_guest.so - allows guest logins

uams_passwd.so or uams_pam.so - allows logins with clear text passwords

uams_randum.so - allows Random Number and Two-Way Random Number Exchange for authentication (requires /etc/atalk//afppaswd file)

-uampath [path]

Sets the default path for UAMs for this server (default is /etc/atalk//uams).

Password Options

-loginmaxmail [number]

Sets the maximum number of failed logins, if supported by the UAM

-passwdfile [path]

Sets the path to the Randnum passwd file for this server (default is /etc/atalk//afppasswd).

-passwdminlen [number]

Sets the minimum password length, if supported by the UAM

-[no]savepassword

Enables or disables the ability of clients to save passwords locally

-[no]setpassword

Enables or disables the ability of clients to change their passwords

Transport Protocols

-[no]ddp

Enables or disables AFP-over-Appletalk. If -proxy is specified, you must instead use -uamlist "" to prevent DDP connections from working.

-[no]tcp

Enables or disables AFP-over-TCP

Transport Options

-admingroup [group]

Allows users of a certain group to be seen as the superuser when they log in. This option is disabled, by default.

-ddpaddr [ddp address]

Specifies the DDP address of the server. The default is to auto-assign an address (0.0). This is only useful if you are running on a multihomed host.

-fqdn [name:port]

Specifies a fully-qualified domain name, with an optional port. This is discarded if the server cannot resolve it. This option is not honored by AppleShare clients <= 3.8.3. This option is disabled by default.

-ipaddr [ip address]

Specifies the IP that the server should respond to (the default is the first IP address of the system). This option also allows one machine to advertise TCP/IP for another machine.

-port [port number]

Allows a different TCP port to be specified for AFP-over-TCP. The default is 548.

-proxy

Runs an AppleTalk proxy server for the specified AFP-over-TCP server. If the address and port aren`t given, then the first IP address of the system and port 548 will be used. If you don`t want the proxy server to act as a DDP server as well, set -uamlist "".

-server_quantum [number]

This specifoes the DSI server quantum. The minimum value is 1 MB. The maximum value is 0xFFFFFFFFF. If you specify a value that is out of range, the default value will be set (which is the minimum).

-noslp

Do not register this server using the Service Location Protocol (if SLP support was compiled in). This is useful if you are running multiple servers and want one to be hidden, perhaps because it is advertised elsewhere.

Miscellaneous Options

-guestname [name]

Specifies the user that guests should use (default is "nobody"). The name should be quoted.

-icon

Use the platform-specific icon

-loginmsg [message]

Sets a message to be displayed when clients logon to the server. The message should be quoted.

-nodebug

Disables debugging

-tickleval [number]

Sets the tickle timeout interval (in seconds).

aliases.sendmail

NAME

aliases - aliases file for sendmail

SYNOPSIS

aliases

DESCRIPTION

This file describes user ID aliases used by sendmail. The file resides in /etc/mail and is formatted as a series of lines of the form

: name: addr_1, addr_2, addr_3, . . .

The name is the name to alias, and the addr_n are the aliases for that name. addr_n can be another alias, a local username, a local filename, a command, an include file, or an external address.

Local Username: username
: The username must be available via getpwnam(3).
Local Filename: /path/name
: Messages are appended to the file specified by the full pathname (starting with a slash (/))
Command: |command
: A command starts with a pipe symbol (|), it receives messages via standard input.
Include File: :include: /path/name
: The aliases in pathname are added to the aliases for name.
E-Mail Address: user@domain
: An e-mail address in RFC 822 format.

Lines beginning with white space are continuation lines. Another way to continue lines is by placing a backslash directly before a newline. Lines beginning with # are comments.

Aliasing occurs only on local names. Loops can not occur, since no message will be sent to any person more than once.

If an alias is found for name, sendmail then checks for an alias for owner-name. If it is found and the result of the lookup expands to a single address, the envelope sender address of the message is rewritten to that address. If it is found and the result expands to more than one address, the envelope sender address is changed to owner-name.

After aliasing has been done, local and valid recipients who have a ``.forward`` file in their home directory have messages forwarded to the list of users defined in that file.

This is only the raw data file; the actual aliasing information is placed into a binary format in the file /etc/mail/aliases.db using the program newaliases(1). A newaliases command should be executed each time the aliases file is changed for the change to take effect.

BUGS

If you have compiled sendmail with DBM support instead of NEWDB, you may have encountered problems in dbm(3) restricting a single alias to about 1000 bytes of information. You can get longer aliases by ``chaining``; that is, make the last name in the alias be a dummy name which is a continuation alias.

HISTORY

The aliases file format appeared in 4.0BSD.

anacrontab

NAME

/etc/anacrontab - configuration file for anacron

DESCRIPTION

The file /etc/anacrontab describes the jobs controlled by anacron(8). Its lines can be of three kinds: job-description lines, environment assignments, or empty lines.

Job-description lines are of the form:

period delay job-identifier command

The period is specified in days, the delay in minutes. The job-identifier can contain any non-blank character, except slashes. It is used to identify the job in Anacron messages, and as the name for the job`s timestamp file. The command can be any shell command.

Environment assignment lines are of the form:

VAR = VALUE

Spaces around VAR are removed. No spaces around VALUE are allowed (unless you want them to be part of the value). The assignment takes effect from the next line to the end of the file, or to the next assignment of the same variable.

Empty lines are either blank lines, line containing white-space only, or lines with white-space followed by a `#` followed by an arbitrary comment.

AUTHOR

Itai Tzur <itzur@actcom.co.il>

appschema

NAME

appschema - LAM application schema format

SYNTAX

# # comments # [<where>] [-np #] [-s <where>] [-wd <dir>] [-x <env>] <program> [<args>] [<where>] [-np #] [-s <where>] [-wd <dir>] [-x <env>] <program> [<args>] ...

DESCRIPTION

The application schema is an ASCII file containing a description of the programs which constitute an application. It is used by mpirun(1), MPI_Comm_spawn, and MPI_Comm_spawn_multiple to start an MPI application (the MPI_Info key "file" can be used to specify an app schema to MPI_Comm_spawn and MPI_Comm_spawn_multiple). All tokens after the program name will be passed as command line arguments to the new processes. Ordering of the other elements on the command line is not important.

The meaning of the options is the same as in mpirun(1). See the mpirun(1) man page for a lengthy discussion of the nomenclature used for <where>. Note, however, that if -wd is used in the application schema file, it will override any -wd value specified on the command line.

For each program line, processes will be created on LAM nodes according to the presence of <where> and the process count option (-np).

only <where>: One process is created on each node.
only -np: The specified number of processes are scheduled across all LAM nodes/CPUs.
both: The specified number of processes are scheduled across the specified nodes/CPUs.
neither: One process is created on the local node.

Program Transfer

By default, LAM searches for executable programs on the target node where a particular instantiation will run. If the file system is not shared, the target nodes are homogeneous, and the program is frequently recompiled, it can be convenient to have LAM transfer the program from a source node (usually the local node) to each target node. The -s option specifies this behaviour and identifies the single source node.

EXAMPLE

# # Example application schema # Note that it may be necessary to specify the entire pathname for # "master" and "slave" if you get "File not found" errors from # mpirun(1). # # This schema starts a "master" process on CPU 0 with the argument # "42.0", and then 10 "slave" processes (that are all sent from the # local node) scheduled across all available CPUs. # c0 master 42.0 C -np 10 -s h slave

atalkd.conf

NAME

atalkd.conf - Configuration file used by atalkd(8) to determine the interfaces used by the master Netatalk daemon

DESCRIPTION

/etc/atalk//atalkd.conf is the configuration file used by atalkd to configure the Appletalk interfaces and their behavior

Any line not prefixed with # is interpreted. The configuration lines are composed like:

interface [ options ]

The simplest case is to have either no atalkd.conf, or to have one that has no active lines. In this case, atalkd should auto-discover the local interfaces on the machine. Please note that you cannot split lines.

The interface is the network interface that this to work over, such as eth0 for Linux, or le0 for Sun.

The possible options and their meanings are:

-addr net.node: Allows specification of the net and node numbers for this interface, specified in Appletalk numbering format (example: -addr 66.6).
-dontroute: Disables Appletalk routing. It is the opposite of -router.
-net first[-last]: Allows the available net to be set, optionally as a range.
-phase ( 1 | 2 ): Specifies the Appletalk phase that this interface is to use (either Phase 1 or Phase 2).
-router: Like -seed, but allows single interface routing. It is the opposite of -dontroute.
-seed: The seed option only works if you have multiple interfaces. It also causes all missing arguments to be automagically configured from the network.
-zone zonename: Specifies a specific zone that this interface should appear on (example: -zone "Parking Lot"). Please note that zones with spaces and other special characters should be enclosed in parentheses.

at_allow

NAME

at.allow, at.deny - determine who can submit jobs via at or batch

DESCRIPTION

The /etc/at.allow and /etc/at.deny files determine which user can submit commands for later execution via at(1) or batch(1).

The format of the files is a list of usernames, one on each line. Whitespace is not permitted.

The superuser may always use at.

If the file /etc/at.allow exists, only usernames mentioned in it are allowed to use at.

If /etc/at.allow does not exist, /etc/at.deny is checked.

autofs

NAME

autofs - Format of the automounter maps

DESCRIPTION

The automounter maps are files or NIS maps referred to by the master map of the automounter (see auto.master(5)). The automounter maps describe how file systems below the mountpoint of the map (given in the auto.master file) are to be mounted. This describes the sun map format; if another map format is specified (e.g. hesiod), this documentation does not apply.

Maps can be changed on the fly and the automouter will recognize those changes on the next operation it performs on that map. This is not true for the auto.master map!

FORMAT

This is a description of the text file format. Other methods of specifying these files may exist. All empty lines or lines beginning with # are ignored. The basic format of one line in such maps is: key [-options] location

key

For indirect mounts this is the part of the pathname between the mountpointi and the path into the filesystem mounted. Usually you can think about the key as a subdirectory name below the mountpoint.

For direct mounts this is the full path of the mountpoint. This map is always associated with the /- mountpoint in the master map.

options

Options are optional. Options can also be given in the auto.master file in which case both values are cumulative (this is a difference from SunOS). The options are a list of comma separated options as customary for the mount(8) command. There are two special options -fstype= used to specify a filesystem type if the filesystem is not of the default NFS type. This option is processed by the automounter and not by the mount command. -strict is used to treat errors when mounting file systems as fatal. This is important when multiple file systems should be mounted (`multimounts`). If this option is given, no file system is mounted at all if at least one file system can`t be mounted.

location

The location specifies from where the file system is to be mounted. In the most cases this will be an NFS volume and the usual notation host:pathname is used to indicate the remote filesystem and path to be mounted. If the filesystem to be mounted begins with a / (such as local /dev entries or smbfs shares) a : needs to be prefixed (e.g. :/dev/sda1).

EXAMPLE

: kernel -ro,soft,intr ftp.kernel.org:/pub/linux boot -fstype=ext2 :/dev/hda1 windoze -fstype=smbfs ://windoze/c removable -fstype=ext2 :/dev/hdd cd -fstype=iso9660,ro :/dev/hdc floppy -fstype=auto :/dev/fd0 server -rw,hard,intr / -ro myserver.me.org:/ /usr myserver.me.org:/usr /home myserver.me.org:/home

In the first line we have a NFS remote mount of the kernel directory on ftp.kernel.org. This is mounted read-only. The second line mounts an ext2 volume on a local ide drive. The third makes a share exported from a Windows machine available for automounting. The rest should be fairly self-explanatory. The last entry (the last three lines) is an example of a multi-map (see below).

If you use the automounter for a filesystem without access permissions (like vfat), users usually can`t write on such a filesystem because it is mounted as user root. You can solve this problem by passing the option gid=<gid>, e. g. gid=floppy. The filesystem is then mounted as group floppy instead of root. Then you can add the users to this group, and they can write to the filesystem. Here`s an example entry for an autofs map:

: floppy-vfat -fstype=vfat,sync,gid=floppy,umask=002 :/dev/fd0

FEATURES

Map Key Substitution

An & character in the location is expanded to the value of the key field that matched the line (which probably only makes sense together with a wildcard key).

Wildcard Key

A * in the key field of indirect maps matches all keys. An example for the usefulness is the following entry:

: * &:/home/&

This will enable you to access all the home directory of local hosts using the path /mountpoint/hostname/local-path.

Variable Substitution

The following special variables will be substituted in the key and location fields of an automounter map if prefixed with $ as customary from shell scripts (Curly braces can be used to separate the fieldname):

: ARCH Architecture (uname -m) CPU Processor Type HOST Hostname (uname -n) OSNAME Operating System (uname -s) OSREL Release of OS (uname -r) OSVERS Version of OS (uname -v)

Additional entries can be defined with the -Dvariable=Value map-option to automount(8).

Executable Maps

A map can be marked as executable. The init script that parses the auto.master map will pass this as a program map to the automounter. A program map will be called as a script with the key as an argument. It may return no lines of output if there`s an error, or one or more lines containing a map (with quoting line breaks). To use a program map, the automount(8) daemon has to be started with the program type instead of the file type. This is implemented in the initialization script. A executable map can return an errorcode to indicate the failure in addition to no output at all. All output sent to stderr is logged into the system logs.

Multiple Mounts

A multi-mount map can be used to name multiple filesystems to mount. It takes the form:

: key [-options] [mountpoint [-options] location...]...

This may extend over multiple lines, quoting the line-breaks with ``. If present, the per-mountpoint mount-options are appended to the default mount-options.

Replicated Server

: Multiple replicated hosts, same path: <path> host1,host2,hostn:/path/path Multiple hosts, some with same path, some with another <path> host1,host2:/blah host3:/some/other/path Multiple replicated hosts, different (potentially) paths: <path> host1:/path/pathA host2:/path/pathB Mutliple weighted, replicated hosts same path: <path> host1(5),host2(6),host3(1):/path/path Multiple weighted, replicated hosts different (potentially) paths: <path> host1(3):/path/pathA host2(5):/path/pathB Anything else is questionable and unsupported, but these variations will also work: <path> host1(3),host:/blah

UNSUPPORTED

This version of the automounter supports direct maps for FILE, NIS and LDAP maps only and handles SunOS-style replicated filesystems only to the extent that mount(8) does.

CAVEATS

Unlike Sun`s multi-mount syntax, the mountpoint is mandatory for all mounts.

AUTHOR

This manual page was written by Christoph Lameter <chris@waterf.org>, for the Debian GNU/Linux system. Edited by H. Peter Anvin <hpa@transmeta.com>, Jeremy Fitzhardinge <jeremy@goop.org> and Ian Kent <raven@themaw.net>.

buffindexed.conf

NAME

buffindexed.conf - configuration file for buffindexed ovmethod

DESCRIPTION

The file <pathetc in inn.conf>/buffindexed.conf is required if buffindexed ovmethod is used.

Buffindexed is one of ovmethod which is specified in inn.conf(5). It uses preconfigured buffer files which are used to store overview data and index, and never needs more disk space other than those files. The files are devided 8KB block internally and the block is allocated for each purpose; overview index and overview data. The block is never shared by each newsgroup, so owned by one newsgroup. There is a database file: <pathdb in inn.conf>/group.index which includes the information of the newsgroup; the pointer to the index block for the group, high mark, low mark, flag of the group, the number of the articles and etc. This file is created automatically when all buffers are initialized and must not be edited manually. If all buffers are filled up, innd(8) throttles itself. Note that the buffer files are never rolled over and overwritten the way CNFS does. You need to append another buffer file in the case. You can see the buffer usage with inndf(8) with ``-o`` option.

The file consists of a series of lines; blank lines and lines beginning with a number sign (``#``) are ignored. There is only one kind of configuration line. The order of lines in this file is not important.

: index:file_name:buffer_size

``Index`` is an index of overview buffer. ``Index`` must be between 0 and 65535. ``File_name`` is the path to overview buffer file. The length of this path should be within 63 letters. ``Buffer_size`` is the length of buffer file in kilobytes in decimal (1KB = 1024 bytes). If the ``file_name`` is not a special device, actucal file size must be buffer_size * 1024 bytes. You can NOT use buffers over 2GB even if you specify <--with-largefiles at configure>. Or buffers will be broken. It`ll be fixed in the future.

To create new overview buffer, there are two different methods for creating the files.

1. Create a big file on top of a standard filesystem.

The use "dd" to create the overview buffer files, such as "dd if=/dev/zero of=/path/to/ovbuff bs=1024 count=N" where N is the buffer_size.

2. Use block disk devices directly.

If your operating system will allow you to mmap() block disk devices (Solaris does, FreeBSD does not), this is the recommended method. But note that Solaris(at least 2.6) seems to have a problem in regional locking of block disk devices, and should not be used. Or overview data will be corrupted. Partition the disks to make each partition slightly larger (a few MB larger) than the intended size of each overview buffer. It is not recommend to use the block device files already located in ``/dev.`` Instead, use "mknod" to create a new set of block device files. In order to do this, do an "ls -Ll" of the /dev/dsk partition. The major and minor device numbers are in the fifth and sixth columns (right before the date) respectively. This information should be fed to "mknod" to make a "block-type special file" (b). Here is a short script that accomplishes this when fed the ``/dev/dsk/`` partition name:

#!/bin/sh disk=$1 major=`ls -l /dev/dsk/$disk | awk `{print $5}` | tr -d ,` minor=`ls -l /dev/dsk/$disk | awk `{print $6}` mkdir /ovbuff mknod /ovbuff/$disk b $major $minor

The created device files themselves consume very little space.

In either case, make certain that each overview buffer file is owned by <USER specified with --with-news-user at configure>, <GROUP specified with --with-news-group at configure>, and has read/write modes for the owner and group (mode ``0664`` or ``0660``).

When you first start innd(8) and everything is configured properly, you should see messages in <pathlog in inn.conf>/news.notice which look like:

Aug 27 00:00:00 kevlar innd: buffindexed: No magic cookie found for buffindexed 0, initializing

You MUST recreate whole overview, if you remove or relpace buffers. You need not recreate, if you just append new buffers. And whenever recreate overview data base, you need to clean all buffers.

HISTORY

Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. This is revision 1.3.2.3, dated 2000/10/12.

charmap

NAME

charmap - character symbols to define character encodings

DESCRIPTION

A character set description (charmap) defines a characterset of available characters and their encodings. All supported character sets should have the portable character set as a proper subset.

SYNTAX

The charmap file starts with a header, that may consist of the following keywords:

<codeset>: is followed by the name of the codeset.
<mb_cur_max>: is followed by the max number of bytes for a multibyte-character. Multibyte characters are currently not supported. The default value is 1.
<mb_cur_min>: is followed by the min number of bytes for a character. This value must be less or equal than mb_cur_max. If not specified, it defaults to mb_cur_max.
<escape_char>: is followed by a character that should be used as the escape-character for the rest of the file to mark characters that should be interpreted in a special way. It defaults to the backslash ( \ ).
<comment_char>: is followed by a character that will be used as the comment-character for the rest of the file. It defaults to the number sign ( # ).

The charmap-definition itself starts with the keyword CHARMAP in column 1.

The following lines may have one of the two following forms to define the character-encodings:

<symbolic-name> <encoding> <comments>: This form defines exactly one character and its encoding.
<symbolic-name>...<symbolic-name> <encoding> <comments>: This form defines a couple of characters. This is only useful for mutlibyte-characters, which are currently not implemented.

The last line in a charmap-definition file must contain END CHARMAP.

SYMBOLIC NAMES

A symbolic name for a character contains only characters of the portable character set. The name itself is enclosed between angle brackets. Characters following an <escape_char> are interpreted as itself; for example, the sequence `<\\\>>` represents the symbolic name `\>` enclosed in angle brackets.

CHARACTER ENCODING

The encoding may be in each of the following three forms:

<escape_char>d<number>

with a decimal number

<escape_char>x<number>

with a hexadecimal number

<escape_char><number>

with an octal number.

FILES

/usr/share/i18n/charmaps/*

AUTHOR

Jochen Hein (jochen.hein@delphi.central.de)

CONFORMING TO

POSIX.2

classes.conf

NAME

classes.conf - class configuration file for cups

DESCRIPTION

The classes.conf file defines the local printer classes that are available. It is normally located in the /etc/cups directory and is generated automatically by the cupsd(8) program when printer classes are added or deleted.

Each line in the file can be a configuration directive, a blank line, or a comment. Comment lines start with the # character.

DIRECTIVES

<Class name> ... </Class>: Defines a specific printer class.
Accepting: Specifies whether or not the printer class is accepting new jobs.
Info: Specifies human-readable text describing the printer class.
Location: Specifies human-readable text describing the location of the printer class.
Printer: Specifies a printer that is a member of the printer class.
State: Specifies the initial state of the printer class (Idle or Stopped)
StateMessage: Specifies the message associated with the state.

COPYRIGHT

complex

NAME

complex - basics of complex mathematics

SYNOPSIS

#include <complex.h>

DESCRIPTION

Complex numbers are numbers of the form z = a+b*i, where a and b are real numbers and i = sqrt(-1), so that i*i = -1.
There are other ways to represent that number. The pair (a,b) of real numbers may be viewed as a point in the plane, given by X- and Y-coordinates. This same point may also be described by giving the pair of real numbers (r,phi), where r is the distance to the origin O, and phi the angle between the X-axis and the line Oz. Now z = r*exp(i*phi) = r*(cos(phi)+i*sin(phi)).

The basic operations are defined on z = a+b*i and w = c+d*i as:

addition: z+w = (a+c) + (b+d)*i
multiplication: z*w = (a*c - b*d) + (a*d + b*c)*i
division: z/w = ((a*c + b*d)/(c*c + d*d)) + ((b*c - a*d)/(c*c + d*d))*i

Nearly all math function have a complex counterpart but there are some complex only functions.

EXAMPLE

Your C-compiler can work with complex numbers if it supports the C99 standard. Link with -lm. The imaginary unit is represented by I.

/* check that exp(i*pi) == -1 */ #include <math.h> /* for atan */ #include <complex.h> main() { double pi = 4*atan(1); complex z = cexp(I*pi); printf("%f+%f*i ", creal(z), cimag(z)); }

config

NAME

config - OpenSSL CONF library configuration files

DESCRIPTION

The OpenSSL CONF library can be used to read configuration files. It is used for the OpenSSL master configuration file openssl.cnf and in a few other places like SPKAC files and certificate extension files for the x509 utility. OpenSSL applications can also use the CONF library for their own purposes.

A configuration file is divided into a number of sections. Each section starts with a line [ section_name ] and ends when a new section is started or end of file is reached. A section name can consist of alphanumeric characters and underscores.

The first section of a configuration file is special and is referred to as the default section this is usually unnamed and is from the start of file until the first named section. When a name is being looked up it is first looked up in a named section (if any) and then the default section.

The environment is mapped onto a section called ENV.

Comments can be included by preceding them with the # character

Each section in a configuration file consists of a number of name and value pairs of the form name=value

The name string can contain any alphanumeric characters as well as a few punctuation symbols such as . , ; and _.

The value string consists of the string following the = character until end of line with any leading and trailing white space removed.

The value string undergoes variable expansion. This can be done by including the form $var or ${var}: this will substitute the value of the named variable in the current section. It is also possible to substitute a value from another section using the syntax $section::name or ${section::name}. By using the form $ENV::name environment variables can be substituted. It is also possible to assign values to environment variables by using the name ENV::name, this will work if the program looks up environment variables using the CONF library instead of calling getenv() directly.

It is possible to escape certain characters by using any kind of quote or the character. By making the last character of a line a a value string can be spread across multiple lines. In addition the sequences , , and are recognized.

OPENSSL LIBRARY CONFIGURATION

In OpenSSL 0.9.7 and later applications can automatically configure certain aspects of OpenSSL using the master OpenSSL configuration file, or optionally an alternative configuration file. The openssl utility includes this functionality: any sub command uses the master OpenSSL configuration file unless an option is used in the sub command to use an alternative configuration file.

To enable library configuration the default section needs to contain an appropriate line which points to the main configuration section. The default name is openssl_conf which is used by the openssl utility. Other applications may use an alternative name such as myapplicaton_conf.

The configuration section should consist of a set of name value pairs which contain specific module configuration information. The name represents the name of the configuration module the meaning of the value is module specific: it may, for example, represent a further configuration section containing configuration module specific information. E.g.

openssl_conf = openssl_init

[openssl_init]

oid_section = new_oids engines = engine_section

[new_oids]

... new oids here ...

[engine_section]

... engine stuff here ...

Currently there are two configuration modules. One for ASN1 objects another for ENGINE configuration.

ASN1 OBJECT CONFIGURATION MODULE

This module has the name oid_section. The value of this variable points to a section containing name value pairs of OIDs: the name is the OID short and long name, the value is the numerical form of the OID. Although some of the openssl utility sub commands already have their own ASN1 OBJECT section functionality not all do. By using the ASN1 OBJECT configuration module all the openssl utility sub commands can see the new objects as well as any compliant applications. For example:

[new_oids]

some_new_oid = 1.2.3.4 some_other_oid = 1.2.3.5

ENGINE CONFIGURATION MODULE

This ENGINE configuration module has the name engines. The value of this variable points to a section containing further ENGINE configuration information.

The section pointed to by engines is a table of engine names (though see engine_id below) and further sections containing configuration informations specific to each ENGINE.

Each ENGINE specific section is used to set default algorithms, load dynamic, perform initialization and send ctrls. The actual operation performed depends on the command name which is the name of the name value pair. The currently supported commands are listed below.

For example:

[engine_section]

# Configure ENGINE named "foo" foo = foo_section # Configure ENGINE named "bar" bar = bar_section

[foo_section] ... foo ENGINE specific commands ...

[bar_section] ... "bar" ENGINE specific commands ...

The command engine_id is used to give the ENGINE name. If used this command must be first. For example:

[engine_section] # This would normally handle an ENGINE named "foo" foo = foo_section

[foo_section] # Override default name and use "myfoo" instead. engine_id = myfoo

The command dynamic_path loads and adds an ENGINE from the given path. It is equivalent to sending the ctrls SO_PATH with the path argument followed by LIST_ADD with value 2 and LOAD to the dynamic ENGINE. If this is not the required behaviour then alternative ctrls can be sent directly to the dynamic ENGINE using ctrl commands.

The command init determines whether to initialize the ENGINE. If the value is 0 the ENGINE will not be initialized, if 1 and attempt it made to initialized the ENGINE immediately. If the init command is not present then an attempt will be made to initialize the ENGINE after all commands in its section have been processed.

The command default_algorithms sets the default algorithms an ENGINE will supply using the functions ENGINE_set_default_string()

If the name matches none of the above command names it is assumed to be a ctrl command which is sent to the ENGINE. The value of the command is the argument to the ctrl command. If the value is the string EMPTY then no value is sent to the command.

For example:

[engine_section]

# Configure ENGINE named "foo" foo = foo_section

[foo_section] # Load engine from DSO dynamic_path = /some/path/fooengine.so # A foo specific ctrl. some_ctrl = some_value # Another ctrl that doesn`t take a value. other_ctrl = EMPTY # Supply all default algorithms default_algorithms = ALL

NOTES

If a configuration file attempts to expand a variable that doesn`t exist then an error is flagged and the file will not load. This can happen if an attempt is made to expand an environment variable that doesn`t exist. For example in a previous version of OpenSSL the default OpenSSL master configuration file used the value of HOME which may not be defined on non Unix systems and would cause an error.

This can be worked around by including a default section to provide a default value: then if the environment lookup fails the default value will be used instead. For this to work properly the default value must be defined earlier in the configuration file than the expansion. See the EXAMPLES section for an example of how to do this.

If the same variable exists in the same section then all but the last value will be silently ignored. In certain circumstances such as with DNs the same field may occur multiple times. This is usually worked around by ignoring any characters before an initial . e.g.

1.OU="My first OU" 2.OU="My Second OU"

EXAMPLES

Here is a sample configuration file using some of the features mentioned above.

# This is the default section.

HOME=/temp RANDFILE= ${ENV::HOME}/.rnd configdir=$ENV::HOME/config

[ section_one ]

# We are now in section one.

# Quotes permit leading and trailing whitespace any = " any variable name "

other = A string that can cover several lines by including \ characters

message = Hello World

[ section_two ]

greeting = $section_one::message

This next example shows how to expand environment variables safely.

Suppose you want a variable called tmpfile to refer to a temporary filename. The directory it is placed in can determined by the the TEMP or TMP environment variables but they may not be set to any value at all. If you just include the environment variable names and the variable doesn`t exist then this will cause an error when an attempt is made to load the configuration file. By making use of the default section both values can be looked up with TEMP taking priority and /tmp used if neither is defined:

TMP=/tmp # The above value is used if TMP isn`t in the environment TEMP=$ENV::TMP # The above value is used if TEMP isn`t in the environment tmpfile=${ENV::TEMP}/tmp.filename

BUGS

Currently there is no way to include characters using the octal nn form. Strings are all null terminated so nulls cannot form part of the value.

The escaping isn`t quite right: if you want to use sequences like you can`t use any quote escaping on the same line.

Files are loaded in a single pass. This means that an variable expansion will only work if the variables referenced are defined earlier in the file.

console.apps

NAME

console.apps - specify console-accessible privileged applications

DESCRIPTION

The /etc/security/console.apps/ directory should contain one file per application that wishes to allow access to console users. The filename should be the same as the servicename, and the contents are irrelevant; the file may be a zero-length file. The application that the file is used by is free to specify the contents in any way that is useful for it.

AUTHOR

Michael K. Johnson <johnsonm@redhat.com>

control.ctl

NAME

control.ctl - specify handling of Usenet control messages

DESCRIPTION

The file <pathetc in inn.conf>/control.ctl is used to determine what action is taken when a control message is received. If <usecontrolchan in inn.conf> is ``true``, it is read by the controlchan script, which can be invoked as channel program by innd(8). When control.ctl is modified, controlchan notices this automatically and reload it. If <usecontrolchan in inn.conf> is ``false``, it is read by the parsecontrol script, which is called by all the control scripts. (For an explanation of how the control scripts are invoked, see innd(8).)

The file consists of a series of lines; blank lines and lines beginning with a number sign (``#``) are ignored. All other lines consist of four fields separated by a colon:

: message:from:newsgroups:action

The first field is the name of the message for which this line is valid. It should be either the name of the control message or the word ``all`` to mean that it is valid for all messages.

The second field is a shell-style pattern that matches the email address of the person posting the message. (The poster`s address is first converted to lowercase.) The matching is done using the shell`s case statement (or the equivalent); see sh(1) for details.

If the control message is ``newgroup`` or ``rmgroup`` then the third field specifies the shell-style pattern that must match the group being created or removed. If the control message is ``checkgroups`` then the third field specifies the shell-style pattern that is used to determine which newsgroups are processed for checking. If the control message is of a different type, then this field is ignored.

The fourth field specifies what action to take on control messages that match this line. The following actions are understood:

doit: The action requested by the control message should be performed. In some cases, the control script will also send mail to <USER specified with --with-news-master at configure>, but if notification of the action should always be sent, doit=mail should be used instead (see below).
doifarg: If the control message has an argument, this is treated as a ``doit`` action. If no argument was given, it is treated as a ``mail`` entry. This is used in ``sendsys`` entries script so that a site can request its own newsfeeds(5) entry by posting a ``sendsys mysite`` article. On the other hand, sendsys ``bombs`` ask that the entire newsfeeds file be sent to a forged reply-to address; by using ``doifarg`` such messages will not be processed automatically. (Processing ``sendsys`` control messages is still not recommended, even with this work-around, unless they are authenticated in some fashion. The risk of having news servers turned into anonymous mail bombing services is too high.)
doit=file: The action is performed, but a log entry is written to the specified log file, file. If file is the word ``mail`` then the record is mailed. A null string is equivalent to /dev/null (in other words, with a null string, nothing is logged). A pathname that starts with a slash is taken as the absolute filename to use as the log. Otherwise, the log entry is written to <pathlog in inn.conf>/file.log. The log is written by writelog (see newslog(8)).
drop: No action is taken; the message is ignored.
verify-*: If the value starts with the string ``verify-`` (for example, ``verify-news.announce.newgroups``) then PGP verification of the control message will be done using the key issued by the ``user`` defined by the rest of the string -- ``news.announce.newsgroups`` in this example. If no logging is specified (with =file mentioned below), notification of successful ``newgroup`` and ``rmgroup`` messages and the output of ``checkgroups`` messages will be mailed to the news administrator.
verify-*=file: PGP verification is done as for the ``verify-*`` entries, and a log entry is written to the specified file. (In the case of ``checkgroups`` messages, this means the shell script output of the ``checkgroups`` message will be written to that file.)
log: A one-line log notice is sent to standard error. innd(8) normally directs this to the file <pathlog in inn.conf>/errlog.
log=file: A log entry is written to the specified log file, file, which is interpreted as described above.
mail: A mail message is sent to the news administrator.

Processing of a ``checkgroups`` message will never actually change the active(5) file. The difference between an action of doit (or verify) and an action of mail for ``checkgroups`` control messages lies only in what mail is sent; doit will mail the news administrator a shell script to create, delete, or modify newsgroups to match the ``checkgroups`` message, whereas mail will just mail the entire message. In either case, the news administrator will have to take action to implement the ``checkgroups`` and if the mail is ignored, nothing will be changed.

Lines are matched in order; the last match found in the file is the one that is used. For example, with the following three lines:

: newgroup:*:*:drop newgroup:group-admin@isc.org:comp.*|humanities.*|misc.*|news.*| rec.*|sci.*|soc.*|talk.*:verify-news.announce.newgroups newgroup:kre@munnari.oz.au:aus.*:mail

A newgroup coming from ``group-admin`` at a ISC machine will be honored if it is one of the listed hierarchies and if it has a valid signature with the ``news.announce.newgroups`` key. If ``kre`` posts a newgroup message creating ``aus.foo``, then mail will be sent. All other newgroup messages are ignored.

Use of the verify action for processing ``newgroup``, ``rmgroup``, and ``checkgroups`` messages is strongly recommended. Abuse of control messages is rampant, and authentication via PGP signatures is currently the only reliable way to be sure that a control message comes from who it claims to be from. Most major hierarchies are now using PGP-authenticated control messages.

In order to use verify actions, the PGP key ring of the news user must be populated with the PGP keys of the hierarchy maintainers whose control messages you want to honor. For more details on PGP-authenticated control messages and the URL for downloading the PGP keys of major hierarchies, see pgpverify(8).

Control messages of type ``cancel`` are handled internally by innd(8) and cannot be controlled by any of the mechanisms described here.

HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is revision 1.11.2.1, dated 2000/08/17.

cvs

NAME

cvs - Concurrent Versions System support files

NOTE

This documentation may no longer be up to date. Please consult the Cederqvist (CVS Manual) as specified in cvs(1).

SYNOPSIS

$CVSROOT/CVSROOT/commitinfo,v
$CVSROOT/CVSROOT/cvsignore,v
$CVSROOT/CVSROOT/cvswrappers,v
$CVSROOT/CVSROOT/editinfo,v
$CVSROOT/CVSROOT/history
$CVSROOT/CVSROOT/loginfo,v
$CVSROOT/CVSROOT/modules,v
$CVSROOT/CVSROOT/rcsinfo,v
$CVSROOT/CVSROOT/taginfo,v

DESCRIPTION

cvs is a system for providing source control to hierarchical collections of source directories. Commands and procedures for using cvs are described in cvs(1).

cvs manages source repositories, the directories containing master copies of the revision-controlled files, by copying particular revisions of the files to (and modifications back from) developers` private working directories. In terms of file structure, each individual source repository is an immediate subdirectory of $CVSROOT.

The files described here are supporting files; they do not have to exist for cvs to operate, but they allow you to make cvs operation more flexible.

You can use the `modules` file to define symbolic names for collections of source maintained with cvs. If there is no `modules` file, developers must specify complete path names (absolute, or relative to $CVSROOT) for the files they wish to manage with cvs commands.

You can use the `commitinfo` file to define programs to execute whenever `cvs commit` is about to execute. These programs are used for ``pre-commit`` checking to verify that the modified, added, and removed files are really ready to be committed. Some uses for this check might be to turn off a portion (or all) of the source repository from a particular person or group. Or, perhaps, to verify that the changed files conform to the site`s standards for coding practice.

You can use the `cvswrappers` file to record cvs wrapper commands to be used when checking files into and out of the repository. Wrappers allow the file or directory to be processed on the way in and out of CVS. The intended uses are many, one possible use would be to reformat a C file before the file is checked in, so all of the code in the repository looks the same.

You can use the `loginfo` file to define programs to execute after any commit, which writes a log entry for changes in the repository. These logging programs might be used to append the log message to a file. Or send the log message through electronic mail to a group of developers. Or, perhaps, post the log message to a particular newsgroup.

You can use the `taginfo` file to define programs to execute after any tagorrtag operation. These programs might be used to append a message to a file listing the new tag name and the programmer who created it, or send mail to a group of developers, or, perhaps, post a message to a particular newsgroup.

You can use the `rcsinfo` file to define forms for log messages.

You can use the `editinfo` file to define a program to execute for editing/validating `cvs commit` log entries. This is most useful when used with a `rcsinfo` forms specification, as it can verify that the proper fields of the form have been filled in by the user committing the change.

You can use the `cvsignore` file to specify the default list of files to ignore during update.

You can use the `history` file to record the cvs commands that affect the repository. The creation of this file enables history logging.

FILES

modules

The `modules` file records your definitions of names for collections of source code. cvs will use these definitions if you use cvs to check in a file with the right format to `$CVSROOT/CVSROOT/modules,v`.

The `modules` file may contain blank lines and comments (lines beginning with `#`) as well as module definitions. Long lines can be continued on the next line by specifying a backslash (````) as the last character on the line.

A module definition is a single line of the `modules` file, in either of two formats. In both cases, mname represents the symbolic module name, and the remainder of the line is its definition.

mname -a aliases...
This represents the simplest way of defining a module mname. The `-a` flags the definition as a simple alias: cvs will treat any use of mname (as a command argument) as if the list of names aliases had been specified instead. aliases may contain either other module names or paths. When you use paths in aliases, `cvs checkout` creates all intermediate directories in the working directory, just as if the path had been specified explicitly in the cvs arguments.

mname [ options ] dir [ files... ] [ &module... ]

In the simplest case, this form of module definition reduces to `mname dir`. This defines all the files in directory dir as module mname. dir is a relative path (from $CVSROOT) to a directory of source in one of the source repositories. In this case, on checkout, a single directory called mname is created as a working directory; no intermediate directory levels are used by default, even if dir was a path involving several directory levels.

By explicitly specifying files in the module definition after dir, you can select particular files from directory dir. The sample definition for modules is an example of a module defined with a single file from a particular directory. Here is another example:

m4test unsupported/gnu/m4 foreach.m4 forloop.m4

With this definition, executing `cvs checkout m4test` will create a single working directory `m4test` containing the two files listed, which both come from a common directory several levels deep in the cvs source repository.

A module definition can refer to other modules by including `&module` in its definition. checkout creates a subdirectory for each such module, in your working directory.
New in cvs 1.3; avoid this feature if sharing module definitions with older versions of cvs.

Finally, you can use one or more of the following options in module definitions:

`-d name`, to name the working directory something other than the module name.
New in cvs 1.3; avoid this feature if sharing module definitions with older versions of cvs.

`-i prog` allows you to specify a program prog to run whenever files in a module are committed. prog runs with a single argument, the full pathname of the affected directory in a source repository. The `commitinfo`, `loginfo`, and `editinfo` files provide other ways to call a program on commit.

`-o prog` allows you to specify a program prog to run whenever files in a module are checked out. prog runs with a single argument, the module name.

`-e prog` allows you to specify a program prog to run whenever files in a module are exported. prog runs with a single argument, the module name.

`-t prog` allows you to specify a program prog to run whenever files in a module are tagged. prog runs with two arguments: the module name and the symbolic tag specified to rtag.

`-u prog` allows you to specify a program prog to run whenever `cvs update` is executed from the top-level directory of the checked-out module. prog runs with a single argument, the full path to the source repository for this module.

commitinfo, loginfo, rcsinfo, editinfo

These files all specify programs to call at different points in the `cvs commit` process. They have a common structure. Each line is a pair of fields: a regular expression, separated by whitespace from a filename or command-line template. Whenever one of the regular expression matches a directory name in the repository, the rest of the line is used. If the line begins with a # character, the entire line is considered a comment and is ignored. Whitespace between the fields is also ignored.

For `loginfo`, the rest of the line is a command-line template to execute. The templates can include not only a program name, but whatever list of arguments you wish. If you write `%s` somewhere on the argument list, cvs supplies, at that point, the list of files affected by the commit. The first entry in the list is the relative path within the source repository where the change is being made. The remaining arguments list the files that are being modified, added, or removed by this commit invocation.

For `taginfo`, the rest of the line is a command-line template to execute. The arguments passed to the command are, in order, the tagname , operation (i.e. add for `tag`, mov for `tag -F`, and del for `tag -d`), repository , and any remaining are pairs of filename revision . A non-zero exit of the filter program will cause the tag to be aborted.

For `commitinfo`, the rest of the line is a command-line template to execute. The template can include not only a program name, but whatever list of arguments you wish. The full path to the current source repository is appended to the template, followed by the file names of any files involved in the commit (added, removed, and modified files).

For `rcsinfo`, the rest of the line is the full path to a file that should be loaded into the log message template.

For `editinfo`, the rest of the line is a command-line template to execute. The template can include not only a program name, but whatever list of arguments you wish. The full path to the current log message template file is appended to the template.

You can use one of two special strings instead of a regular expression: `ALL` specifies a command line template that must always be executed, and `DEFAULT` specifies a command line template to use if no regular expression is a match.

The `commitinfo` file contains commands to execute before any other commit activity, to allow you to check any conditions that must be satisfied before commit can proceed. The rest of the commit will execute only if all selected commands from this file exit with exit status 0.

The `rcsinfo` file allows you to specify log templates for the commit logging session; you can use this to provide a form to edit when filling out the commit log. The field after the regular expression, in this file, contains filenames (of files containing the logging forms) rather than command templates.

The `editinfo` file allows you to execute a script before the commit starts, but after the log information is recorded. These "edit" scripts can verify information recorded in the log file. If the edit script exits with a non-zero exit status, the commit is aborted.

The `loginfo` file contains commands to execute at the end of a commit. The text specified as a commit log message is piped through the command; typical uses include sending mail, filing an article in a newsgroup, or appending to a central file.

cvsignore, .cvsignore

The default list of files (or sh(1) file name patterns) to ignore during `cvs update`. At startup time, cvs loads the compiled in default list of file name patterns (see cvs(1)). Then the per-repository list included in $CVSROOT/CVSROOT/cvsignore is loaded, if it exists. Then the per-user list is loaded from `$HOME/.cvsignore`. Finally, as cvs traverses through your directories, it will load any per-directory `.cvsignore` files whenever it finds one. These per-directory files are only valid for exactly the directory that contains them, not for any sub-directories.

history

Create this file in $CVSROOT/CVSROOT to enable history logging (see the description of `cvs history`).

COPYING

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.

cycbuff.conf

NAME

cycbuff.conf - configuration file for CNFS method

DESCRIPTION

The file <pathetc in inn.conf>/cycbuff.conf is required if CNFS (Cyclic News File System) method is used. CNFS is one of storage method which can be defined at storage.conf(5).

The file consists of a series of lines; blank lines and lines beginning with a number sign (``#``) are ignored. There are four kinds of configuration lines: ``cycbuffupdate``, ``refreshinterval``, ``cycbuff`` and ``metacycbuff.`` The order of lines in this file is not important among the same kind of configuration line. But all ``cycbuff`` lines should be presented before any ``metacycbuff`` lines.

``Cycbuffupdate`` line is formatted as:

: cycbuffupdate:update

``Update`` is how many article-stores between cycbuff header updates. This line can be omitted and the default value is ``25.``

``Refreshinterval`` line is formatted as:

: refreshinterval:interval

``Inerval`` is what interval (seconds) between rereading cycbuff header if cycbuff is preopend. (This is in the case nnrpd(8) runs as a daemon.) This line can be omitted and the default value is ``30.``

``Cycbuff`` line is formatted as:

: cycbuff:buffer_name:file_name:buffer_size

``Buffer_name`` is the symbolic name of the buffer. The length of this name should be within 7 letters. This name is referred at ``metacycbuff`` lines. ``File_name`` is the path to buffer file. The length of this path should be within 63 letters. ``Buffer_size`` is the length of buffer file in kilobytes in decimal (1KB = 1024 bytes). If the ``file_name`` is not a special device, the file should be buffer_size * 1024 bytes.

``Metacycbuff`` line is formatted as:

: metacycbuff:meta_cyclic_buffer_name:buffer_names[:mode]

``Meta_cyclic_buffer_name`` is the symbolic name of meta-cyclic buffer. This name is referred at ``options`` field at ``cnfs`` entries in storage.conf(5). ``Buffer_names`` is comma separated list of symbolic names of ``cycbuff.`` These buffer names should be defined at ``cycbuff`` lines. If ``buffer_names`` has more than one buffer names, CNFS method stores articles into each ``cycbuff`` in order cyclically. ``Mode`` is the mode of storing article. Currently there are two mode; ``INTERLEAVE`` and ``SEQUENTIAL``. Mode ``INTERLEAVE`` is to store articles into each cycbuff in round robin way. Mode ``SEQUENTIAL`` is to store articles sequentially into one cycbuff until it is filled up. ``Mode`` is optional and the default value without this option is ``INTERLEAVE``.

Also it is necessary to set up ``options`` field at ``cnfs`` entries in storage.conf(5) to use CNFS method. That field should be one of ``meta_cyclic_buffer_name`` defined at ``metacycbuff`` lines.

To create new ``cycbuff``, there are two different methods for creating the cyclic buffer files.

1. Create a big file on top of a standard filesystem.

The use "dd" to create the ``cycbuff`` files, such as "dd if=/dev/zero of=/path/to/cycbuff bs=32k count=N" where N is the buffer_size divided by 32.

2. Use block disk devices directly.

If your operating system will allow you to mmap() block disk devices (Solaris does, FreeBSD does not), this is the recommended method. Partition the disks to make each partition slightly larger (a few MB larger) than the intended size of each cycbuff. It is not recommend to use the block device files already located in ``/dev.`` Instead, use "mknod" to create a new set of block device files. In order to do this, do an "ls -Ll" of the /dev/dsk partition. The major and minor device numbers are in the fifth and sixth columns (right before the date) respectively. This information should be fed to "mknod" to make a "block-type special file" (b). Here is a short script that accomplishes this when fed the ``/dev/dsk/`` partition name:

#!/bin/sh disk=$1 link=`ls -l /dev/dsk/$disk | awk `{print $11}`` major=`ls -l /dev/dsk/$link | awk `{print $5}` | tr -d ,` minor=`ls -l /dev/dsk/$link | awk `{print $6}` mkdir /cycbuff mknod /cycbuff/$disk b $major $minor

The created device files themselves consume very little space.

When you first start innd and everything is configured properly, you should see messages in news.notice which look like:

Mar 1 00:00:00 kevlar innd: CNFS-sm No magic cookie found for cycbuff ONE, initializing

HISTORY

Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. This is revision 1.13.2.1, dated 2000/08/17.

default.session

NAME

GNOME Default session configuration file.

The /usr/share/gnome/default.session file contains a list of programs to be launched the first time a user logs into the GNOME environment.

The format of the file is the one used by the gnome_config libraries, and it looks like this:

[Section] SEQID,id=uniqueID SEQID,Priority=PRIO SEQID,RestartCommand=command num_clients=TOP

There are three possible names for Section And they are:

Default

: This specifies the Default session to load

Chooser

: Lets the user configure which non-session aware programs should be started up when the session begins

Warner

Since the gnome_config file format is not very flexible, an array of data is emulated by listing starting from 0 chunks of "id,Priority,RestartCommand", and at the end the num_clients variable lists the number of chunks listed.

The uniqueid key provides a name that is unique within this file and passed to the app as the client id which it must use to register with gnome-session.

The RestartCommand specifies the command to run from the $PATH.

The Priority determines the order in which the commands are started (with Priority = 0 first) and defaults to 50.

The clients must be numbered from 0 to the value of num_clients-1

dhclient.conf

NAME

dhclient.conf - DHCP client configuration file

DESCRIPTION

The dhclient.conf file contains configuration information for dhclient, the Internet Systems Consortium DHCP Client.

The dhclient.conf file is a free-form ASCII text file. It is parsed by the recursive-descent parser built into dhclient. The file may contain extra tabs and newlines for formatting purposes. Keywords in the file are case-insensitive. Comments may be placed anywhere within the file (except within quotes). Comments begin with the # character and end at the end of the line.

The dhclient.conf file can be used to configure the behaviour of the client in a wide variety of ways: protocol timing, information requested from the server, information required of the server, defaults to use if the server does not provide certain information, values with which to override information provided by the server, or values to prepend or append to information provided by the server. The configuration file can also be preinitialized with addresses to use on networks that don`t have DHCP servers.

PROTOCOL TIMING

The timing behaviour of the client need not be configured by the user. If no timing configuration is provided by the user, a fairly reasonable timing behaviour will be used by default - one which results in fairly timely updates without placing an inordinate load on the server.

The following statements can be used to adjust the timing behaviour of the DHCP client if required, however:

The timeout statement

timeout time ;

The timeout statement determines the amount of time that must pass between the time that the client begins to try to determine its address and the time that it decides that it`s not going to be able to contact a server. By default, this timeout is sixty seconds. After the timeout has passed, if there are any static leases defined in the configuration file, or any leases remaining in the lease database that have not yet expired, the client will loop through these leases attempting to validate them, and if it finds one that appears to be valid, it will use that lease`s address. If there are no valid static leases or unexpired leases in the lease database, the client will restart the protocol after the defined retry interval.

The retry statement

retry time;

The retry statement determines the time that must pass after the client has determined that there is no DHCP server present before it tries again to contact a DHCP server. By default, this is five minutes.

The select-timeout statement

select-timeout time;

It is possible (some might say desirable) for there to be more than one DHCP server serving any given network. In this case, it is possible that a client may be sent more than one offer in response to its initial lease discovery message. It may be that one of these offers is preferable to the other (e.g., one offer may have the address the client previously used, and the other may not).

The select-timeout is the time after the client sends its first lease discovery request at which it stops waiting for offers from servers, assuming that it has received at least one such offer. If no offers have been received by the time the select-timeout has expired, the client will accept the first offer that arrives.

By default, the select-timeout is zero seconds - that is, the client will take the first offer it sees.

The reboot statement

reboot time;

When the client is restarted, it first tries to reacquire the last address it had. This is called the INIT-REBOOT state. If it is still attached to the same network it was attached to when it last ran, this is the quickest way to get started. The reboot statement sets the time that must elapse after the client first tries to reacquire its old address before it gives up and tries to discover a new address. By default, the reboot timeout is ten seconds.

The backoff-cutoff statement

backoff-cutoff time;

The client uses an exponential backoff algorithm with some randomness, so that if many clients try to configure themselves at the same time, they will not make their requests in lockstep. The backoff-cutoff statement determines the maximum amount of time that the client is allowed to back off. It defaults to two minutes.

The initial-interval statement

initial-interval time;

The initial-interval statement sets the amount of time between the first attempt to reach a server and the second attempt to reach a server. Each time a message is sent, the interval between messages is incremented by twice the current interval multiplied by a random number between zero and one. If it is greater than the backoff-cutoff amount, it is set to that amount. It defaults to ten seconds.

LEASE REQUIREMENTS AND REQUESTS

The DHCP protocol allows the client to request that the server send it specific information, and not send it other information that it is not prepared to accept. The protocol also allows the client to reject offers from servers if they don`t contain information the client needs, or if the information provided is not satisfactory.

There is a variety of data contained in offers that DHCP servers send to DHCP clients. The data that can be specifically requested is what are called DHCP Options. DHCP Options are defined in
dhcp-options(5).

The request statement

request [ option ] [, ... option ];

The request statement causes the client to request that any server responding to the client send the client its values for the specified options. Only the option names should be specified in the request statement - not option parameters. By default, the DHCP server requests the subnet-mask, broadcast-address, time-offset, routers, domain-name, domain-name-servers, host-name, nis-domain, nis-servers, and ntp-servers options.

In some cases, it may be desirable to send no parameter request list at all. To do this, simply write the request statement but specify no parameters:

request;

The require statement

require [ option ] [, ... option ];

The require statement lists options that must be sent in order for an offer to be accepted. Offers that do not contain all the listed options will be ignored.

The send statement

send { [ option declaration ] [, ... option declaration ]}

The send statement causes the client to send the specified options to the server with the specified values. These are full option declarations as described in dhcp-options(5). Options that are always sent in the DHCP protocol should not be specified here, except that the client can specify a requested-lease-time option other than the default requested lease time, which is two hours. The other obvious use for this statement is to send information to the server that will allow it to differentiate between this client and other clients or kinds of clients.

DYNAMIC DNS

The client now has some very limited support for doing DNS updates when a lease is acquired. This is prototypical, and probably doesn`t do what you want. It also only works if you happen to have control over your DNS server, which isn`t very likely.

To make it work, you have to declare a key and zone as in the DHCP server (see dhcpd.conf(5) for details). You also need to configure the fqdn option on the client, as follows:

send fqdn.fqdn "grosse.fugue.com."; send fqdn.encoded on; send fqdn.server-update off;

The fqdn.fqdn option MUST be a fully-qualified domain name. You MUST define a zone statement for the zone to be updated. The fqdn.encoded option may need to be set to on or off, depending on the DHCP server you are using.

The do-forward-updates statement

do-forward-updates [ flag ] ;

If you want to do DNS updates in the DHCP client script (see dhclient-script(8)) rather than having the DHCP client do the update directly (for example, if you want to use SIG(0) authentication, which is not supported directly by the DHCP client, you can instruct the client not to do the update using the do-forward-updates statement. Flag should be true if you want the DHCP client to do the update, and false if you don`t want the DHCP client to do the update. By default, the DHCP client will do the DNS update.

OPTION MODIFIERS

In some cases, a client may receive option data from the server which is not really appropriate for that client, or may not receive information that it needs, and for which a useful default value exists. It may also receive information which is useful, but which needs to be supplemented with local information. To handle these needs, several option modifiers are available.

The default statement

default [ option declaration ] ;

If for some option the client should use the value supplied by the server, but needs to use some default value if no value was supplied by the server, these values can be defined in the default statement.

The supersede statement

supersede [ option declaration ] ;

If for some option the client should always use a locally-configured value or values rather than whatever is supplied by the server, these values can be defined in the supersede statement.

The prepend statement

prepend [ option declaration ] ;

If for some set of options the client should use a value you supply, and then use the values supplied by the server, if any, these values can be defined in the prepend statement. The prepend statement can only be used for options which allow more than one value to be given. This restriction is not enforced - if you ignore it, the behaviour will be unpredictable.

The append statement

append [ option declaration ] ;

If for some set of options the client should first use the values supplied by the server, if any, and then use values you supply, these values can be defined in the append statement. The append statement can only be used for options which allow more than one value to be given. This restriction is not enforced - if you ignore it, the behaviour will be unpredictable.

LEASE DECLARATIONS

The lease declaration

lease { lease-declaration [ ... lease-declaration ] }

The DHCP client may decide after some period of time (see PROTOCOL TIMING) that it is not going to succeed in contacting a server. At that time, it consults its own database of old leases and tests each one that has not yet timed out by pinging the listed router for that lease to see if that lease could work. It is possible to define one or more fixed leases in the client configuration file for networks where there is no DHCP or BOOTP service, so that the client can still automatically configure its address. This is done with the lease statement.

NOTE: the lease statement is also used in the dhclient.leases file in order to record leases that have been received from DHCP servers. Some of the syntax for leases as described below is only needed in the dhclient.leases file. Such syntax is documented here for completeness.

A lease statement consists of the lease keyword, followed by a left curly brace, followed by one or more lease declaration statements, followed by a right curly brace. The following lease declarations are possible:

bootp;

The bootp statement is used to indicate that the lease was acquired using the BOOTP protocol rather than the DHCP protocol. It is never necessary to specify this in the client configuration file. The client uses this syntax in its lease database file.

interface "string";

The interface lease statement is used to indicate the interface on which the lease is valid. If set, this lease will only be tried on a particular interface. When the client receives a lease from a server, it always records the interface number on which it received that lease. If predefined leases are specified in the dhclient.conf file, the interface should also be specified, although this is not required.

fixed-address ip-address;

The fixed-address statement is used to set the ip address of a particular lease. This is required for all lease statements. The IP address must be specified as a dotted quad (e.g., 12.34.56.78).

filename "string";

The filename statement specifies the name of the boot filename to use. This is not used by the standard client configuration script, but is included for completeness.

server-name "string";

The server-name statement specifies the name of the boot server name to use. This is also not used by the standard client configuration script.

option option-declaration;

The option statement is used to specify the value of an option supplied by the server, or, in the case of predefined leases declared in dhclient.conf, the value that the user wishes the client configuration script to use if the predefined lease is used.

script "script-name";

The script statement is used to specify the pathname of the dhcp client configuration script. This script is used by the dhcp client to set each interface`s initial configuration prior to requesting an address, to test the address once it has been offered, and to set the interface`s final configuration once a lease has been acquired. If no lease is acquired, the script is used to test predefined leases, if any, and also called once if no valid lease can be identified. For more information, see dhclient-script(8).

vendor option space "name";

The vendor option space statement is used to specify which option space should be used for decoding the vendor-encapsulate-options option if one is received. The dhcp-vendor-identifier can be used to request a specific class of vendor options from the server. See dhcp-options(5) for details.

medium "media setup";

The medium statement can be used on systems where network interfaces cannot automatically determine the type of network to which they are connected. The media setup string is a system-dependent parameter which is passed to the dhcp client configuration script when initializing the interface. On Unix and Unix-like systems, the argument is passed on the ifconfig command line when configuring the interface.

The dhcp client automatically declares this parameter if it uses a media type (see the media statement) when configuring the interface in order to obtain a lease. This statement should be used in predefined leases only if the network interface requires media type configuration.

renew date;

rebind date;

expire date;

The renew statement defines the time at which the dhcp client should begin trying to contact its server to renew a lease that it is using. The rebind statement defines the time at which the dhcp client should begin to try to contact any dhcp server in order to renew its lease. The expire statement defines the time at which the dhcp client must stop using a lease if it has not been able to contact a server in order to renew it.

These declarations are automatically set in leases acquired by the DHCP client, but must also be configured in predefined leases - a predefined lease whose expiry time has passed will not be used by the DHCP client.

Dates are specified as follows:

<weekday> <year>/<month>/<day> <hour>:<minute>:<second>

The weekday is present to make it easy for a human to tell when a lease expires - it`s specified as a number from zero to six, with zero being Sunday. When declaring a predefined lease, it can always be specified as zero. The year is specified with the century, so it should generally be four digits except for really long leases. The month is specified as a number starting with 1 for January. The day of the month is likewise specified starting with 1. The hour is a number between 0 and 23, the minute a number between 0 and 59, and the second also a number between 0 and 59.

ALIAS DECLARATIONS

alias { declarations ... }

Some DHCP clients running TCP/IP roaming protocols may require that in addition to the lease they may acquire via DHCP, their interface also be configured with a predefined IP alias so that they can have a permanent IP address even while roaming. The Internet Systems Consortium DHCP client doesn`t support roaming with fixed addresses directly, but in order to facilitate such experimentation, the dhcp client can be set up to configure an IP alias using the alias declaration.

The alias declaration resembles a lease declaration, except that options other than the subnet-mask option are ignored by the standard client configuration script, and expiry times are ignored. A typical alias declaration includes an interface declaration, a fixed-address declaration for the IP alias address, and a subnet-mask option declaration. A medium statement should never be included in an alias declaration.

OTHER DECLARATIONS

reject ip-address;

The reject statement causes the DHCP client to reject offers from servers who use the specified address as a server identifier. This can be used to avoid being configured by rogue or misconfigured dhcp servers, although it should be a last resort - better to track down the bad DHCP server and fix it.

interface "name" { declarations ... }

A client with more than one network interface may require different behaviour depending on which interface is being configured. All timing parameters and declarations other than lease and alias declarations can be enclosed in an interface declaration, and those parameters will then be used only for the interface that matches the specified name. Interfaces for which there is no interface declaration will use the parameters declared outside of any interface declaration, or the default settings.

pseudo "name" "real-name" { declarations ... }

Under some circumstances it can be useful to declare a pseudo-interface and have the DHCP client acquire a configuration for that interface. Each interface that the DHCP client is supporting normally has a DHCP client state machine running on it to acquire and maintain its lease. A pseudo-interface is just another state machine running on the interface named real-name, with its own lease and its own state. If you use this feature, you must provide a client identifier for both the pseudo-interface and the actual interface, and the two identifiers must be different. You must also provide a separate client script for the pseudo-interface to do what you want with the IP address. For example:

interface "ep0" { send dhcp-client-identifier "my-client-ep0"; } pseudo "secondary" "ep0" { send dhcp-client-identifier "my-client-ep0-secondary"; script "/etc/dhclient-secondary"; }

The client script for the pseudo-interface should not configure the interface up or down - essentially, all it needs to handle are the states where a lease has been acquired or renewed, and the states where a lease has expired. See dhclient-script(8) for more information.

media "media setup" [ , "media setup", ... ];

The media statement defines one or more media configuration parameters which may be tried while attempting to acquire an IP address. The dhcp client will cycle through each media setup string on the list, configuring the interface using that setup and attempting to boot, and then trying the next one. This can be used for network interfaces which aren`t capable of sensing the media type unaided - whichever media type succeeds in getting a request to the server and hearing the reply is probably right (no guarantees).

The media setup is only used for the initial phase of address acquisition (the DHCPDISCOVER and DHCPOFFER packets). Once an address has been acquired, the dhcp client will record it in its lease database and will record the media type used to acquire the address. Whenever the client tries to renew the lease, it will use that same media type. The lease must expire before the client will go back to cycling through media types.

SAMPLE

The following configuration file is used on a laptop running NetBSD 1.3. The laptop has an IP alias of 192.5.5.213, and has one interface, ep0 (a 3com 3C589C). Booting intervals have been shortened somewhat from the default, because the client is known to spend most of its time on networks with little DHCP activity. The laptop does roam to multiple networks.

timeout 60; retry 60; reboot 10; select-timeout 5; initial-interval 2; reject 192.33.137.209; interface "ep0" { send host-name "andare.fugue.com"; send dhcp-client-identifier 1:0:a0:24:ab:fb:9c; send dhcp-lease-time 3600; supersede domain-name "fugue.com rc.vix.com home.vix.com"; prepend domain-name-servers 127.0.0.1; request subnet-mask, broadcast-address, time-offset, routers, domain-name, domain-name-servers, host-name; require subnet-mask, domain-name-servers; script "/sbin/dhclient-script"; media "media 10baseT/UTP", "media 10base2/BNC"; } alias { interface "ep0"; fixed-address 192.5.5.213; option subnet-mask 255.255.255.255; }

This is a very complicated dhclient.conf file - in general, yours should be much simpler. In many cases, it`s sufficient to just create an empty dhclient.conf file - the defaults are usually fine.

AUTHOR

dhclient(8) was written by Ted Lemon under a contract with Vixie Labs. Funding for this project was provided by Internet Systems Consortium. Information about Internet Systems Consortium can be found at http://www.isc.org.

dhcp-eval

NAME

dhcp-eval - ISC DHCP conditional evaluation

DESCRIPTION

The Internet Systems Consortium DHCP client and server both provide the ability to perform conditional behavior depending on the contents of packets they receive. The syntax for specifying this conditional behaviour is documented here.

REFERENCE: CONDITIONAL BEHAVIOUR

Conditional behaviour is specified using the if statement and the else or elsif statements. A conditional statement can appear anywhere that a regular statement (e.g., an option statement) can appear, and can enclose one or more such statements. A typical conditional statement in a server might be:

if option dhcp-user-class = "accounting" { max-lease-time 17600; option domain-name "accounting.example.org"; option domain-name-servers ns1.accounting.example.org, ns2.accounting.example.org; } elsif option dhcp-user-class = "sales" { max-lease-time 17600; option domain-name "sales.example.org"; option domain-name-servers ns1.sales.example.org, ns2.sales.example.org; } elsif option dhcp-user-class = "engineering" { max-lease-time 17600; option domain-name "engineering.example.org"; option domain-name-servers ns1.engineering.example.org, ns2.engineering.example.org; } else { max-lease-time 600; option domain-name "misc.example.org"; option domain-name-servers ns1.misc.example.org, ns2.misc.example.org; }

On the client side, an example of conditional evaluation might be:

# example.org filters DNS at its firewall, so we have to use their DNS # servers when we connect to their network. If we are not at # example.org, prefer our own DNS server. if not option domain-name = "example.org" { prepend domain-name-servers 127.0.0.1; }

The if statement and the elsif continuation statement both take boolean expressions as their arguments. That is, they take expressions that, when evaluated, produce a boolean result. If the expression evaluates to true, then the statements enclosed in braces following the if statement are executed, and all subsequent elsif and else clauses are skipped. Otherwise, each subsequent elsif clause`s expression is checked, until an elsif clause is encountered whose test evaluates to true. If such a clause is found, the statements in braces following it are executed, and then any subsequent elsif and else clauses are skipped. If all the if and elsif clauses are checked but none of their expressions evaluate true, then if there is an else clause, the statements enclosed in braces following the else are evaluated. Boolean expressions that evaluate to null are treated as false in conditionals.

BOOLEAN EXPRESSIONS

The following is the current list of boolean expressions that are supported by the DHCP distribution.

data-expression-1 = data-expression-2

: The = operator compares the values of two data expressions, returning true if they are the same, false if they are not. If either the left-hand side or the right-hand side are null, the result is also null.

boolean-expression-1 and boolean-expression-2

: The and operator evaluates to true if the boolean expression on the left-hand side and the boolean expression on the right-hand side both evaluate to true. Otherwise, it evaluates to false. If either the expression on the left-hand side or the expression on the right-hand side are null, the result is null.

boolean-expression-1 or boolean-expression-2

: The or operator evaluates to true if either the boolean expression on the left-hand side or the boolean expression on the right-hand side evaluate to true. Otherwise, it evaluates to false. If either the expression on the left-hand side or the expression on the right-hand side are null, the result is null.

not boolean-expression

: The not operator evaluates to true if boolean-expression evaluates to false, and returns false if boolean-expression evaluates to true. If boolean-expression evaluates to null, the result is also null.

exists option-name

: The exists expression returns true if the specified option exists in the incoming DHCP packet being processed.

known

: The known expression returns true if the client whose request is currently being processed is known - that is, if there`s a host declaration for it.

static

: The static expression returns true if the lease assigned to the client whose request is currently being processed is derived from a static address assignment.

DATA EXPRESSIONS

Several of the boolean expressions above depend on the results of evaluating data expressions. A list of these expressions is provided here.

substring (data-expr, offset, length)

: The substring operator evaluates the data expression and returns the substring of the result of that evaluation that starts offset bytes from the beginning, continuing for length bytes. Offset and length are both numeric expressions. If data-expr, offset or length evaluate to null, then the result is also null. If offset is greater than or equal to the length of the evaluated data, then a zero-length data string is returned. If length is greater then the remaining length of the evaluated data after offset, then a data string containing all data from offset to the end of the evaluated data is returned.

suffix (data-expr, length)

: The suffix operator evaluates data-expr and returns the last length bytes of the result of that evaluation. Length is a numeric expression. If data-expr or length evaluate to null, then the result is also null. If suffix evaluates to a number greater than the length of the evaluated data, then the evaluated data is returned.

option option-name

: The option operator returns the contents of the specified option in the packet to which the server is responding.

config-option option-name

: The config-option operator returns the value for the specified option that the DHCP client or server has been configured to send.

hardware

: The hardware operator returns a data string whose first element is the type of network interface indicated in packet being considered, and whose subsequent elements are client`s link-layer address. If there is no packet, or if the RFC2131 hlen field is invalid, then the result is null. Hardware types include ethernet (1), token-ring (6), and fddi (8). Hardware types are specified by the IETF, and details on how the type numbers are defined can be found in RFC2131 (in the ISC DHCP distribution, this is included in the doc/ subdirectory).

packet (offset, length)

: The packet operator returns the specified portion of the packet being considered, or null in contexts where no packet is being considered. Offset and length are applied to the contents packet as in the substring operator.

string

: A string, enclosed in quotes, may be specified as a data expression, and returns the text between the quotes, encoded in ASCII. The backslash (``) character is treated specially, as in C programming: t` means TAB, ` ` means carriage return, ` ` means newline, and b` means bell. Any octal value can be specified with ` nn`, where nnn is any positive octal number less than 0400. Any hexadecimal value can be specified with ``, where nn is any positive hexadecimal number less than 0xff.

colon-separated hexadecimal list

: A list of hexadecimal octet values, separated by colons, may be specified as a data expression.

concat (data-expr1, ..., data-exprN)

: The expressions are evaluated, and the results of each evaluation are concatenated in the sequence that the subexpressions are listed. If any subexpression evaluates to null, the result of the concatenation is null.

reverse (numeric-expr1, data-expr2)

: The two expressions are evaluated, and then the result of evaluating the data expression is reversed in place, using hunks of the size specified in the numeric expression. For example, if the numeric expression evaluates to four, and the data expression evaluates to twelve bytes of data, then the reverse expression will evaluate to twelve bytes of data, consisting of the last four bytes of the the input data, followed by the middle four bytes, followed by the first four bytes.

leased-address

: In any context where the client whose request is being processed has been assigned an IP address, this data expression returns that IP address.

binary-to-ascii (numeric-expr1, numeric-expr2, data-expr1, data-expr2)

: Converts the result of evaluating data-expr2 into a text string containing one number for each element of the result of evaluating data-expr2. Each number is separated from the other by the result of evaluating data-expr1. The result of evaluating numeric-expr1 specifies the base (2 through 16) into which the numbers should be converted. The result of evaluating numeric-expr2 specifies the width in bits of each number, which may be either 8, 16 or 32.
As an example of the preceding three types of expressions, to produce the name of a PTR record for the IP address being assigned to a client, one could write the following expression:

concat (binary-to-ascii (10, 8, ".", reverse (1, leased-address)), ".in-addr.arpa.");

encode-int (numeric-expr, width)

Numeric-expr is evaluated and encoded as a data string of the specified width, in network byte order (most significant byte first). If the numeric expression evaluates to the null value, the result is also null.

pick-first-value (data-expr1 [ ... exprn ] )

: The pick-first-value function takes any number of data expressions as its arguments. Each expression is evaluated, starting with the first in the list, until an expression is found that does not evaluate to a null value. That expression is returned, and none of the subsequent expressions are evaluated. If all expressions evaluate to a null value, the null value is returned.

host-decl-name

: The host-decl-name function returns the name of the host declaration that matched the client whose request is currently being processed, if any. If no host declaration matched, the result is the null value.

NUMERIC EXPRESSIONS

Numeric expressions are expressions that evaluate to an integer. In general, the maximum size of such an integer should not be assumed to be representable in fewer than 32 bits, but the precision of such integers may be more than 32 bits.

extract-int (data-expr, width)

: The extract-int operator extracts an integer value in network byte order from the result of evaluating the specified data expression. Width is the width in bits of the integer to extract. Currently, the only supported widths are 8, 16 and 32. If the evaluation of the data expression doesn`t provide sufficient bits to extract an integer of the specified size, the null value is returned.

lease-time

: The duration of the current lease - that is, the difference between the current time and the time that the lease expires.

number

: Any number between zero and the maximum representable size may be specified as a numeric expression.

client-state

The current state of the client instance being processed. This is only useful in DHCP client configuration files. Possible values are:

*: Booting - DHCP client is in the INIT state, and does not yet have an IP address. The next message transmitted will be a DHCPDISCOVER, which will be broadcast.
*: Reboot - DHCP client is in the INIT-REBOOT state. It has an IP address, but is not yet using it. The next message to be transmitted will be a DHCPREQUEST, which will be broadcast. If no response is heard, the client will bind to its address and move to the BOUND state.
*: Select - DHCP client is in the SELECTING state - it has received at least one DHCPOFFER message, but is waiting to see if it may receive other DHCPOFFER messages from other servers. No messages are sent in the SELECTING state.
*: Request - DHCP client is in the REQUESTING state - it has received at least one DHCPOFFER message, and has chosen which one it will request. The next message to be sent will be a DHCPREQUEST message, which will be broadcast.
*: Bound - DHCP client is in the BOUND state - it has an IP address. No messages are transmitted in this state.
*: Renew - DHCP client is in the RENEWING state - it has an IP address, and is trying to contact the server to renew it. The next message to be sent will be a DHCPREQUEST message, which will be unicast directly to the server.
*: Rebind - DHCP client is in the REBINDING state - it has an IP address, and is trying to contact any server to renew it. The next message to be sent will be a DHCPREQUEST, which will be broadcast.

REFERENCE: LOGGING

Logging statements may be used to send information to the standard logging channels. A logging statement includes an optional priority (fatal, error, info, or debug), and a data expression.

log (priority, data-expr)

Logging statements take only a single data expression argument, so if you want to output multiple data values, you will need to use the concat operator to concatenate them.

REFERENCE: DYNAMIC DNS UPDATES

The DHCP client and server have the ability to dynamically update the Domain Name System. Within the configuration files, you can define how you want the Domain Name System to be updated. These updates are RFC 2136 compliant so any DNS server supporting RFC 2136 should be able to accept updates from the DHCP server.

SECURITY

Support for TSIG and DNSSEC is not yet available. When you set your DNS server up to allow updates from the DHCP server or client, you may be exposing it to unauthorized updates. To avoid this, the best you can do right now is to use IP address-based packet filtering to prevent unauthorized hosts from submitting update requests. Obviously, there is currently no way to provide security for client updates - this will require TSIG or DNSSEC, neither of which is yet available in the DHCP distribution.

Dynamic DNS (DDNS) updates are performed by using the dns-update expression. The dns-update expression is a boolean expression that takes four parameters. If the update succeeds, the result is true. If it fails, the result is false. The four parameters that the are the resource record type (RR), the left hand side of the RR, the right hand side of the RR and the ttl that should be applied to the record. The simplest example of the use of the function can be found in the reference section of the dhcpd.conf file, where events are described. In this example several statements are being used to make the arguments to the dns-updateR.

In the example, the first argument to the first Bdns-update expression is a data expression that evaluates to the A RR type. The second argument is constructed by concatenating the DHCP host-name option with a text string containing the local domain, in this case "ssd.example.net". The third argument is constructed by converting the address the client has been assigned from a 32-bit number into an ascii string with each byte separated by a ".". The fourth argument, the TTL, specifies the amount of time remaining in the lease (note that this isn`t really correct, since the DNS server will pass this TTL out whenever a request comes in, even if that is only a few seconds before the lease expires).

If the first dns-update statement succeeds, it is followed up with a second update to install a PTR RR. The installation of a PTR record is similar to installing an A RR except that the left hand side of the record is the leased address, reversed, with ".in-addr.arpa" concatenated. The right hand side is the fully qualified domain name of the client to which the address is being leased.

AUTHOR

The Internet Systems Consortium DHCP Distribution was written by Ted Lemon under a contract with Vixie Labs. Funding for this project was provided through Internet Systems Consortium. Information about Internet Systems Consortium can be found at http://www.isc.org.

dhcp6c.conf

NAME

dhcp6c.conf - configuration file of the DHCPv6 client daemon, dhcp6c

DESCRIPTION

dhcp6c.conf is a configuration file for dhcp6c (DHCPv6 client). dhcp6c is configured by the configuration information (such as rapid-commit, requesting temp-address, or prefix-delegation) in this file. dhcp6c.conf is an ASCII text file and lines that start with # are comments.

STATEMENTS

interface <interface name> { [declarations] };

Write configurations for this interface in this statement. In [declarations], options can be specified.

DECLARATIONS

send [dhcpoptions];

With this declaration, dhcp6c sends specified options. Currently rapid-commit is defined.

send rapid-commit;

This declaration enables dhcp6c to request the dhcp6s server to perform a Rapid Commit.

request [dhcpoptions];

This declaration enables dhcp6c to request specified options. Currently temp-address, domain-name-servers, and prefix-delegation are defined.

request domain-name-servers;

The DHCPv6 mechanism provides a way to obtain configuration information such as a list of available DNS servers or NTP servers. This declaration enables dhcp6c to request a DNS server address from the DHCPv6 server.

request prefix-delegation;

This declaration enables dhcp6c to request a Prefix Delegation to the DHCPv6 server. dhcp6c gets a prefix assignment from the DHCPv6 server.

request temp-address;

This declaration enables dhcp6c to request temporary addresses. dhcp6c requests Non-temporary Addresses as default. This option makes dhcp6c request Temporary Addresses.

information-only;

This declaration enables dhcp6c to request host configuration information from the DHCPv6 server. If dhcp6c doesn`t need to be assigned any addresses, this option should be specified.

address { [<ipv6 address>/<prefix length>]; [prefer-life-time <preferred-lifetime>]; [valid-life-time <valid-lifetime>]; };

This declaration defines the dhcp6c client preferred IPv6 address, the preferred lifetime of the address, and the valid lifetime for this interface.

prefix { [<ipv6 prefix>/<prefix length>]; [prefer-life-time <preferred-lifetime>]; [valid-life-time <valid-lifetime>]; };

This declaration defines the dhcp6c client acting as a requesting router for the preferred prefix, the prefix length, and the prefix`s preferred lifetime, and valid lifetime for this interface.

prefer-life-time <preferred-lifetime>;

This declaration sets the preferred lifetime (in seconds) of the address or prefix. This declaration is valid only in address or prefix declarations.

valid-life-time <valid-lifetime>;

This declaration sets the valid lifetime (in seconds) of the address or prefix. This declaration is valid only in address or prefix declarations.

renew-time <renew-time>;

This declaration specifies the Renew Time (in seconds) for this Identity Association (IA). Renew Time is a T1 value in an IA option. dhcp6c sets the Renew Time in IA options to the specified value.

rebind-time <rebind-time>;

This declaration specifies the Rebind Time (in seconds) for this IA. Rebind Time is T2 value in an IA option. dhcp6c sets the Rebind Time in IA options to the specified value.

DHCPOPTIONS

rapid-commit

If this option is used in a "send [dhcpoptions];" declaration, dhcp6c sends DHCPv6 messages with a Rapid Commit option.

domain-name-servers

If this option is used in a "request [dhcpoptions];" declaration, dhcp6c requests the DNS server address via the DHCPv6 mechanism.

prefix-delegation

If this option is used in a "request [dhcpoptions];" declaration, dhcp6c requests a Prefix Delegation to the DHCPv6 servers.

EXAMPLES

This is a sample of the dhcp6c.conf file.

interface eth0 { send rapid-commit; request prefix-delegation; request domain-name-servers; request temp-address; iaid 11111; address { 3ffe:10::10/64; prefer-life-time 6000; valid-life-time 8000; }; renew-time 11000; rebind-time 21000; };

AUTHORS

Kazuo Hiekata <hiekata@yamato.ibm.com>

dhcpd.conf

NAME

dhcpd.conf - dhcpd configuration file

DESCRIPTION

The dhcpd.conf file contains configuration information for dhcpd, the Internet Systems Consortium DHCP Server.

The dhcpd.conf file is a free-form ASCII text file. It is parsed by the recursive-descent parser built into dhcpd. The file may contain extra tabs and newlines for formatting purposes. Keywords in the file are case-insensitive. Comments may be placed anywhere within the file (except within quotes). Comments begin with the # character and end at the end of the line.

The file essentially consists of a list of statements. Statements fall into two broad categories - parameters and declarations.

Parameter statements either say how to do something (e.g., how long a lease to offer), whether to do something (e.g., should dhcpd provide addresses to unknown clients), or what parameters to provide to the client (e.g., use gateway 220.177.244.7).

Declarations are used to describe the topology of the network, to describe clients on the network, to provide addresses that can be assigned to clients, or to apply a group of parameters to a group of declarations. In any group of parameters and declarations, all parameters must be specified before any declarations which depend on those parameters may be specified.

Declarations about network topology include the shared-network and the subnet declarations. If clients on a subnet are to be assigned addresses dynamically, a range declaration must appear within the subnet declaration. For clients with statically assigned addresses, or for installations where only known clients will be served, each such client must have a host declaration. If parameters are to be applied to a group of declarations which are not related strictly on a per-subnet basis, the group declaration can be used.

For every subnet which will be served, and for every subnet to which the dhcp server is connected, there must be one subnet declaration, which tells dhcpd how to recognize that an address is on that subnet. A subnet declaration is required for each subnet even if no addresses will be dynamically allocated on that subnet.

Some installations have physical networks on which more than one IP subnet operates. For example, if there is a site-wide requirement that 8-bit subnet masks be used, but a department with a single physical ethernet network expands to the point where it has more than 254 nodes, it may be necessary to run two 8-bit subnets on the same ethernet until such time as a new physical network can be added. In this case, the subnet declarations for these two networks must be enclosed in a shared-network declaration.

Some sites may have departments which have clients on more than one subnet, but it may be desirable to offer those clients a uniform set of parameters which are different than what would be offered to clients from other departments on the same subnet. For clients which will be declared explicitly with host declarations, these declarations can be enclosed in a group declaration along with the parameters which are common to that department. For clients whose addresses will be dynamically assigned, class declarations and conditional declarations may be used to group parameter assignments based on information the client sends.

When a client is to be booted, its boot parameters are determined by consulting that client`s host declaration (if any), and then consulting any class declarations matching the client, followed by the pool, subnet and shared-network declarations for the IP address assigned to the client. Each of these declarations itself appears within a lexical scope, and all declarations at less specific lexical scopes are also consulted for client option declarations. Scopes are never considered twice, and if parameters are declared in more than one scope, the parameter declared in the most specific scope is the one that is used.

When dhcpd tries to find a host declaration for a client, it first looks for a host declaration which has a fixed-address declaration that lists an IP address that is valid for the subnet or shared network on which the client is booting. If it doesn`t find any such entry, it tries to find an entry which has no fixed-address declaration.

EXAMPLES

A typical dhcpd.conf file will look something like this:

global parameters... subnet 204.254.239.0 netmask 255.255.255.224 { subnet-specific parameters... range 204.254.239.10 204.254.239.30; } subnet 204.254.239.32 netmask 255.255.255.224 { subnet-specific parameters... range 204.254.239.42 204.254.239.62; } subnet 204.254.239.64 netmask 255.255.255.224 { subnet-specific parameters... range 204.254.239.74 204.254.239.94; } group { group-specific parameters... host zappo.test.isc.org { host-specific parameters... } host beppo.test.isc.org { host-specific parameters... } host harpo.test.isc.org { host-specific parameters... } } <CENTER> Figure 1
</CENTER>

Notice that at the beginning of the file, there`s a place for global parameters. These might be things like the organization`s domain name, the addresses of the name servers (if they are common to the entire organization), and so on. So, for example:

option domain-name "isc.org"; option domain-name-servers ns1.isc.org, ns2.isc.org; <CENTER> Figure 2
</CENTER>

As you can see in Figure 2, you can specify host addresses in parameters using their domain names rather than their numeric IP addresses. If a given hostname resolves to more than one IP address (for example, if that host has two ethernet interfaces), then where possible, both addresses are supplied to the client.

The most obvious reason for having subnet-specific parameters as shown in Figure 1 is that each subnet, of necessity, has its own router. So for the first subnet, for example, there should be something like:

option routers 204.254.239.1;

Note that the address here is specified numerically. This is not required - if you have a different domain name for each interface on your router, it`s perfectly legitimate to use the domain name for that interface instead of the numeric address. However, in many cases there may be only one domain name for all of a router`s IP addresses, and it would not be appropriate to use that name here.

In Figure 1 there is also a group statement, which provides common parameters for a set of three hosts - zappo, beppo and harpo. As you can see, these hosts are all in the test.isc.org domain, so it might make sense for a group-specific parameter to override the domain name supplied to these hosts:

option domain-name "test.isc.org";

Also, given the domain they`re in, these are probably test machines. If we wanted to test the DHCP leasing mechanism, we might set the lease timeout somewhat shorter than the default:

max-lease-time 120; default-lease-time 120;

You may have noticed that while some parameters start with the option keyword, some do not. Parameters starting with the option keyword correspond to actual DHCP options, while parameters that do not start with the option keyword either control the behavior of the DHCP server (e.g., how long a lease dhcpd will give out), or specify client parameters that are not optional in the DHCP protocol (for example, server-name and filename).

In Figure 1, each host had host-specific parameters. These could include such things as the hostname option, the name of a file to upload (the filename parameter) and the address of the server from which to upload the file (the next-server parameter). In general, any parameter can appear anywhere that parameters are allowed, and will be applied according to the scope in which the parameter appears.

Imagine that you have a site with a lot of NCD X-Terminals. These terminals come in a variety of models, and you want to specify the boot files for each model. One way to do this would be to have host declarations for each server and group them by model:

group { filename "Xncd19r"; next-server ncd-booter; host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; } host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; } host ncd8 { hardware ethernet 0:c0:c3:22:46:81; } } group { filename "Xncd19c"; next-server ncd-booter; host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; } host ncd3 { hardware ethernet 0:c0:c3:00:14:11; } } group { filename "XncdHMX"; next-server ncd-booter; host ncd1 { hardware ethernet 0:c0:c3:11:90:23; } host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; } host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; } }

ADDRESS POOLS

The pool declaration can be used to specify a pool of addresses that will be treated differently than another pool of addresses, even on the same network segment or subnet. For example, you may want to provide a large set of addresses that can be assigned to DHCP clients that are registered to your DHCP server, while providing a smaller set of addresses, possibly with short lease times, that are available for unknown clients. If you have a firewall, you may be able to arrange for addresses from one pool to be allowed access to the Internet, while addresses in another pool are not, thus encouraging users to register their DHCP clients. To do this, you would set up a pair of pool declarations:

subnet 10.0.0.0 netmask 255.255.255.0 { option routers 10.0.0.254; # Unknown clients get this pool. pool { option domain-name-servers bogus.example.com; max-lease-time 300; range 10.0.0.200 10.0.0.253; allow unknown-clients; } # Known clients get this pool. pool { option domain-name-servers ns1.example.com, ns2.example.com; max-lease-time 28800; range 10.0.0.5 10.0.0.199; deny unknown-clients; } }

It is also possible to set up entirely different subnets for known and unknown clients - address pools exist at the level of shared networks, so address ranges within pool declarations can be on different subnets.

As you can see in the preceding example, pools can have permit lists that control which clients are allowed access to the pool and which aren`t. Each entry in a pool`s permit list is introduced with the allow or deny keyword. If a pool has a permit list, then only those clients that match specific entries on the permit list will be eligible to be assigned addresses from the pool. If a pool has a deny list, then only those clients that do not match any entries on the deny list will be eligible. If both permit and deny lists exist for a pool, then only clients that match the permit list and do not match the deny list will be allowed access.

DYNAMIC ADDRESS ALLOCATION

Address allocation is actually only done when a client is in the INIT state and has sent a DHCPDISCOVER message. If the client thinks it has a valid lease and sends a DHCPREQUEST to initiate or renew that lease, the server has only three choices - it can ignore the DHCPREQUEST, send a DHCPNAK to tell the client it should stop using the address, or send a DHCPACK, telling the client to go ahead and use the address for a while.

If the server finds the address the client is requesting, and that address is available to the client, the server will send a DHCPACK. If the address is no longer available, or the client isn`t permitted to have it, the server will send a DHCPNAK. If the server knows nothing about the address, it will remain silent, unless the address is incorrect for the network segment to which the client has been attached and the server is authoritative for that network segment, in which case the server will send a DHCPNAK even though it doesn`t know about the address.

There may be a host declaration matching the client`s identification. If that host declaration contains a fixed-address declaration that lists an IP address that is valid for the network segment to which the client is connected. In this case, the DHCP server will never do dynamic address allocation. In this case, the client is required to take the address specified in the host declaration. If the client sends a DHCPREQUEST for some other address, the server will respond with a DHCPNAK.

When the DHCP server allocates a new address for a client (remember, this only happens if the client has sent a DHCPDISCOVER), it first looks to see if the client already has a valid lease on an IP address, or if there is an old IP address the client had before that hasn`t yet been reassigned. In that case, the server will take that address and check it to see if the client is still permitted to use it. If the client is no longer permitted to use it, the lease is freed if the server thought it was still in use - the fact that the client has sent a DHCPDISCOVER proves to the server that the client is no longer using the lease.

If no existing lease is found, or if the client is forbidden to receive the existing lease, then the server will look in the list of address pools for the network segment to which the client is attached for a lease that is not in use and that the client is permitted to have. It looks through each pool declaration in sequence (all range declarations that appear outside of pool declarations are grouped into a single pool with no permit list). If the permit list for the pool allows the client to be allocated an address from that pool, the pool is examined to see if there is an address available. If so, then the client is tentatively assigned that address. Otherwise, the next pool is tested. If no addresses are found that can be assigned to the client, no response is sent to the client.

If an address is found that the client is permitted to have, and that has never been assigned to any client before, the address is immediately allocated to the client. If the address is available for allocation but has been previously assigned to a different client, the server will keep looking in hopes of finding an address that has never before been assigned to a client.

The DHCP server generates the list of available IP addresses from a hash table. This means that the addresses are not sorted in any particular order, and so it is not possible to predict the order in which the DHCP server will allocate IP addresses. Users of previous versions of the ISC DHCP server may have become accustomed to the DHCP server allocating IP addresses in ascending order, but this is no longer possible, and there is no way to configure this behavior with version 3 of the ISC DHCP server.

IP ADDRESS CONFLICT PREVENTION

The DHCP server checks IP addresses to see if they are in use before allocating them to clients. It does this by sending an ICMP Echo request message to the IP address being allocated. If no ICMP Echo reply is received within a second, the address is assumed to be free. This is only done for leases that have been specified in range statements, and only when the lease is thought by the DHCP server to be free - i.e., the DHCP server or its failover peer has not listed the lease as in use.

If a response is received to an ICMP Echo request, the DHCP server assumes that there is a configuration error - the IP address is in use by some host on the network that is not a DHCP client. It marks the address as abandoned, and will not assign it to clients.

If a DHCP client tries to get an IP address, but none are available, but there are abandoned IP addresses, then the DHCP server will attempt to reclaim an abandoned IP address. It marks one IP address as free, and then does the same ICMP Echo request check described previously. If there is no answer to the ICMP Echo request, the address is assigned to the client.

The DHCP server does not cycle through abandoned IP addresses if the first IP address it tries to reclaim is free. Rather, when the next DHCPDISCOVER comes in from the client, it will attempt a new allocation using the same method described here, and will typically try a new IP address.

DHCP FAILOVER

This version of the ISC DHCP server supports the DHCP failover protocol as documented in draft-ietf-dhc-failover-07.txt. This is not a final protocol document, and we have not done interoperability testing with other vendors` implementations of this protocol, so you must not assume that this implementation conforms to the standard. If you wish to use the failover protocol, make sure that both failover peers are running the same version of the ISC DHCP server.

The failover protocol allows two DHCP servers (and no more than two) to share a common address pool. Each server will have about half of the available IP addresses in the pool at any given time for allocation. If one server fails, the other server will continue to renew leases out of the pool, and will allocate new addresses out of the roughly half of available addresses that it had when communications with the other server were lost.

It is possible during a prolonged failure to tell the remaining server that the other server is down, in which case the remaining server will (over time) reclaim all the addresses the other server had available for allocation, and begin to reuse them. This is called putting the server into the PARTNER-DOWN state.

You can put the server into the PARTNER-DOWN state either by using the omshell (1) command or by stopping the server, editing the last peer state declaration in the lease file, and restarting the server. If you use this last method, be sure to leave the date and time of the start of the state blank:

failover peer name state { my state partner-down; peer state state at date; }

When the other server comes back online, it should automatically detect that it has been offline and request a complete update from the server that was running in the PARTNER-DOWN state, and then both servers will resume processing together.

It is possible to get into a dangerous situation: if you put one server into the PARTNER-DOWN state, and then *that* server goes down, and the other server comes back up, the other server will not know that the first server was in the PARTNER-DOWN state, and may issue addresses previously issued by the other server to different clients, resulting in IP address conflicts. Before putting a server into PARTNER-DOWN state, therefore, make sure that the other server will not restart automatically.

The failover protocol defines a primary server role and a secondary server role. There are some differences in how primaries and secondaries act, but most of the differences simply have to do with providing a way for each peer to behave in the opposite way from the other. So one server must be configured as primary, and the other must be configured as secondary, and it doesn`t matter too much which one is which.

FAILOVER STARTUP

When a server starts that has not previously communicated with its failover peer, it must establish communications with its failover peer and synchronize with it before it can serve clients. This can happen either because you have just configured your DHCP servers to perform failover for the first time, or because one of your failover servers has failed catastrophically and lost its database.

The initial recovery process is designed to ensure that when one failover peer loses its database and then resynchronizes, any leases that the failed server gave out before it failed will be honored. When the failed server starts up, it notices that it has no saved failover state, and attempts to contact its peer.

When it has established contact, it asks the peer for a complete copy its peer`s lease database. The peer then sends its complete database, and sends a message indicating that it is done. The failed server then waits until MCLT has passed, and once MCLT has passed both servers make the transition back into normal operation. This waiting period ensures that any leases the failed server may have given out while out of contact with its partner will have expired.

While the failed server is recovering, its partner remains in the partner-down state, which means that it is serving all clients. The failed server provides no service at all to DHCP clients until it has made the transition into normal operation.

In the case where both servers detect that they have never before communicated with their partner, they both come up in this recovery state and follow the procedure we have just described. In this case, no service will be provided to DHCP clients until MCLT has expired.

CONFIGURING FAILOVER

In order to configure failover, you need to write a peer declaration that configures the failover protocol, and you need to write peer references in each pool declaration for which you want to do failover. You do not have to do failover for all pools on a given network segment. You must not tell one server it`s doing failover on a particular address pool and tell the other it is not. You must not have any common address pools on which you are not doing failover. A pool declaration that utilizes failover would look like this:

pool { failover peer "foo"; deny dynamic bootp clients; pool specific parameters };

Dynamic BOOTP leases are not compatible with failover, and, as such, you need to disallow BOOTP in pools that you are using failover for.

The server currently does very little sanity checking, so if you configure it wrong, it will just fail in odd ways. I would recommend therefore that you either do failover or don`t do failover, but don`t do any mixed pools. Also, use the same master configuration file for both servers, and have a separate file that contains the peer declaration and includes the master file. This will help you to avoid configuration mismatches. As our implementation evolves, this will become less of a problem. A basic sample dhcpd.conf file for a primary server might look like this:

failover peer "foo" { primary; address anthrax.rc.vix.com; port 519; peer address trantor.rc.vix.com; peer port 520; max-response-delay 60; max-unacked-updates 10; mclt 3600; split 128; load balance max seconds 3; } include "/etc/dhcpd.master";

The statements in the peer declaration are as follows:

The primary and secondary statements

[ primary | secondary ];

This determines whether the server is primary or secondary, as described earlier under DHCP FAILOVER.

The address statement

address address;

The address statement declares the IP address or DNS name on which the server should listen for connections from its failover peer, and also the value to use for the DHCP Failover Protocol server identifier. Because this value is used as an identifier, it may not be omitted.

The peer address statement

peer address address;

The peer address statement declares the IP address or DNS name to which the server should connect to reach its failover peer for failover messages.

The port statement

port port-number;

The port statement declares the TCP port on which the server should listen for connections from its failover peer. This statement may not currently be omitted, because the failover protocol does not yet have a reserved TCP port number.

The peer port statement

peer port port-number;

The peer port statement declares the TCP port to which the server should connect to reach its failover peer for failover messages. This statement may not be omitted because the failover protocol does not yet have a reserved TCP port number. The port number declared in the peer port statement may be the same as the port number declared in the port statement.

The max-response-delay statement

max-response-delay seconds;

The max-response-delay statement tells the DHCP server how many seconds may pass without receiving a message from its failover peer before it assumes that connection has failed. This number should be small enough that a transient network failure that breaks the connection will not result in the servers being out of communication for a long time, but large enough that the server isn`t constantly making and breaking connections. This parameter must be specified.

The max-unacked-updates statement

max-unacked-updates count;

The max-unacked-updates statement tells the DHCP server how many BNDUPD messages it can send before it receives a BNDACK from the failover peer. We don`t have enough operational experience to say what a good value for this is, but 10 seems to work. This parameter must be specified.

The mclt statement

mclt seconds;

The mclt statement defines the Maximum Client Lead Time. It must be specified on the primary, and may not be specified on the secondary. This is the length of time for which a lease may be renewed by either failover peer without contacting the other. The longer you set this, the longer it will take for the running server to recover IP addresses after moving into PARTNER-DOWN state. The shorter you set it, the more load your servers will experience when they are not communicating. A value of something like 3600 is probably reasonable, but again bear in mind that we have no real operational experience with this.

The split statement

split index;

The split statement specifies the split between the primary and secondary for the purposes of load balancing. Whenever a client makes a DHCP request, the DHCP server runs a hash on the client identification. If the hash comes out to less than the split value, the primary answers. If it comes out to equal to or more than the split, the secondary answers. The only meaningful value is 128, and can only be configured on the primary.

The hba statement

hba colon-separated-hex-list;

The hba statement specifies the split between the primary and secondary as a bitmap rather than a cutoff, which theoretically allows for finer-grained control. In practice, there is probably no need for such fine-grained control, however. An example hba statement:

hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff: 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00;

This is equivalent to a split 128; statement. You must only have split or hba defined, never both. For most cases, the fine-grained control that hba offers isn`t necessary, and split should be used. As such, the use of hba is deprecated.

The load balance max seconds statement

load balance max seconds seconds;

This statement allows you to configure a cutoff after which load balancing is disabled. The cutoff is based on the number of seconds since the client sent its first DHCPDISCOVER or DHCPREQUEST message, and only works with clients that correctly implement the secs field - fortunately most clients do. We recommend setting this to something like 3 or 5. The effect of this is that if one of the failover peers gets into a state where it is responding to failover messages but not responding to some client requests, the other failover peer will take over its client load automatically as the clients retry.

CLIENT CLASSING

Clients can be separated into classes, and treated differently depending on what class they are in. This separation can be done either with a conditional statement, or with a match statement within the class declaration. It is possible to specify a limit on the total number of clients within a particular class or subclass that may hold leases at one time, and it is possible to specify automatic subclassing based on the contents of the client packet.

To add clients to classes based on conditional evaluation, you can specify a matching expression in the class statement:

class "ras-clients" { match if substring (option dhcp-client-identifier, 1, 3) = "RAS"; }

Note that whether you use matching expressions or add statements (or both) to classify clients, you must always write a class declaration for any class that you use. If there will be no match statement and no in-scope statements for a class, the declaration should look like this:

class "ras-clients" { }

SUBCLASSES

In addition to classes, it is possible to declare subclasses. A subclass is a class with the same name as a regular class, but with a specific submatch expression which is hashed for quick matching. This is essentially a speed hack - the main difference between five classes with match expressions and one class with five subclasses is that it will be quicker to find the subclasses. Subclasses work as follows:

class "allocation-class-1" { match pick-first-value (option dhcp-client-identifier, hardware); } class "allocation-class-2" { match pick-first-value (option dhcp-client-identifier, hardware); } subclass "allocation-class-1" 1:8:0:2b:4c:39:ad; subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3; subclass "allocation-class-1" 1:0:0:c4:aa:29:44; subnet 10.0.0.0 netmask 255.255.255.0 { pool { allow members of "allocation-class-1"; range 10.0.0.11 10.0.0.50; } pool { allow members of "allocation-class-2"; range 10.0.0.51 10.0.0.100; } }

The data following the class name in the subclass declaration is a constant value to use in matching the match expression for the class. When class matching is done, the server will evaluate the match expression and then look the result up in the hash table. If it finds a match, the client is considered a member of both the class and the subclass.

Subclasses can be declared with or without scope. In the above example, the sole purpose of the subclass is to allow some clients access to one address pool, while other clients are given access to the other pool, so these subclasses are declared without scopes. If part of the purpose of the subclass were to define different parameter values for some clients, you might want to declare some subclasses with scopes.

In the above example, if you had a single client that needed some configuration parameters, while most didn`t, you might write the following subclass declaration for that client:

subclass "allocation-class-2" 1:08:00:2b:a1:11:31 { option root-path "samsara:/var/diskless/alphapc"; filename "/tftpboot/netbsd.alphapc-diskless"; }

In this example, we`ve used subclassing as a way to control address allocation on a per-client basis. However, it`s also possible to use subclassing in ways that are not specific to clients - for example, to use the value of the vendor-class-identifier option to determine what values to send in the vendor-encapsulated-options option. An example of this is shown under the VENDOR ENCAPSULATED OPTIONS head in the dhcp-options(5) manual page.

PER-CLASS LIMITS ON DYNAMIC ADDRESS ALLOCATION

You may specify a limit to the number of clients in a class that can be assigned leases. The effect of this will be to make it difficult for a new client in a class to get an address. Once a class with such a limit has reached its limit, the only way a new client in that class can get a lease is for an existing client to relinquish its lease, either by letting it expire, or by sending a DHCPRELEASE packet. Classes with lease limits are specified as follows:

class "limited-1" { lease limit 4; }

This will produce a class in which a maximum of four members may hold a lease at one time.

SPAWNING CLASSES

It is possible to declare a spawning class. A spawning class is a class that automatically produces subclasses based on what the client sends. The reason that spawning classes were created was to make it possible to create lease-limited classes on the fly. The envisioned application is a cable-modem environment where the ISP wishes to provide clients at a particular site with more than one IP address, but does not wish to provide such clients with their own subnet, nor give them an unlimited number of IP addresses from the network segment to which they are connected.

Many cable modem head-end systems can be configured to add a Relay Agent Information option to DHCP packets when relaying them to the DHCP server. These systems typically add a circuit ID or remote ID option that uniquely identifies the customer site. To take advantage of this, you can write a class declaration as follows:

class "customer" { spawn with option agent.circuit-id; lease limit 4; }

Now whenever a request comes in from a customer site, the circuit ID option will be checked against the class`s hash table. If a subclass is found that matches the circuit ID, the client will be classified in that subclass and treated accordingly. If no subclass is found matching the circuit ID, a new one will be created and logged in the dhcpd.leases file, and the client will be classified in this new class. Once the client has been classified, it will be treated according to the rules of the class, including, in this case, being subject to the per-site limit of four leases.

The use of the subclass spawning mechanism is not restricted to relay agent options - this particular example is given only because it is a fairly straightforward one.

COMBINING MATCH, MATCH IF AND SPAWN WITH

In some cases, it may be useful to use one expression to assign a client to a particular class, and a second expression to put it into a subclass of that class. This can be done by combining the match if and spawn with statements, or the match if and match statements. For example:

class "jr-cable-modems" { match if option dhcp-vendor-identifier = "jrcm"; spawn with option agent.circuit-id; lease limit 4; } class "dv-dsl-modems" { match if opton dhcp-vendor-identifier = "dvdsl"; spawn with option agent.circuit-id; lease limit 16; }

This allows you to have two classes that both have the same spawn with expression without getting the clients in the two classes confused with each other.

DYNAMIC DNS UPDATES

The DHCP server has the ability to dynamically update the Domain Name System. Within the configuration files, you can define how you want the Domain Name System to be updated. These updates are RFC 2136 compliant so any DNS server supporting RFC 2136 should be able to accept updates from the DHCP server.

Two DNS update schemes are currently implemented, and another is planned. The two that are currently available are the ad-hoc DNS update mode and the interim DHCP-DNS interaction draft update mode. If and when the DHCP-DNS interaction draft and the DHCID draft make it through the IETF standards process, there will be a third mode, which will be the standard DNS update method. The DHCP server must be configured to use one of the two currently-supported methods, or not to do dns updates. This can be done with the ddns-update-style configuration parameter.

THE AD-HOC DNS UPDATE SCHEME

The ad-hoc Dynamic DNS update scheme is now deprecated and does not work. In future releases of the ISC DHCP server, this scheme will not likely be available. The interim scheme works, allows for failover, and should now be used. The following description is left here for informational purposes only.

The ad-hoc Dynamic DNS update scheme implemented in this version of the ISC DHCP server is a prototype design, which does not have much to do with the standard update method that is being standardized in the IETF DHC working group, but rather implements some very basic, yet useful, update capabilities. This mode does not work with the failover protocol because it does not account for the possibility of two different DHCP servers updating the same set of DNS records.

For the ad-hoc DNS update method, the client`s FQDN is derived in two parts. First, the hostname is determined. Then, the domain name is determined, and appended to the hostname.

The DHCP server determines the client`s hostname by first looking for a ddns-hostname configuration option, and using that if it is present. If no such option is present, the server looks for a valid hostname in the FQDN option sent by the client. If one is found, it is used; otherwise, if the client sent a host-name option, that is used. Otherwise, if there is a host declaration that applies to the client, the name from that declaration will be used. If none of these applies, the server will not have a hostname for the client, and will not be able to do a DNS update.

The domain name is determined based strictly on the server configuration, not on what the client sends. First, if there is a ddns-domainname configuration option, it is used. Second, if there is a domain-name option configured, that is used. Otherwise, the server will not do the DNS update.

The client`s fully-qualified domain name, derived as we have described, is used as the name on which an "A" record will be stored. The A record will contain the IP address that the client was assigned in its lease. If there is already an A record with the same name in the DNS server, no update of either the A or PTR records will occur - this prevents a client from claiming that its hostname is the name of some network server. For example, if you have a fileserver called "fs.sneedville.edu", and the client claims its hostname is "fs", no DNS update will be done for that client, and an error message will be logged.

If the A record update succeeds, a PTR record update for the assigned IP address will be done, pointing to the A record. This update is unconditional - it will be done even if another PTR record of the same name exists. Since the IP address has been assigned to the DHCP server, this should be safe.

Please note that the current implementation assumes clients only have a single network interface. A client with two network interfaces will see unpredictable behavior. This is considered a bug, and will be fixed in a later release. It may be helpful to enable the one-lease-per-client parameter so that roaming clients do not trigger this same behavior.

The DHCP protocol normally involves a four-packet exchange - first the client sends a DHCPDISCOVER message, then the server sends a DHCPOFFER, then the client sends a DHCPREQUEST, then the server sends a DHCPACK. In the current version of the server, the server will do a DNS update after it has received the DHCPREQUEST, and before it has sent the DHCPACK. It only sends the DNS update if it has not sent one for the client`s address before, in order to minimize the impact on the DHCP server.

When the client`s lease expires, the DHCP server (if it is operating at the time, or when next it operates) will remove the client`s A and PTR records from the DNS database. If the client releases its lease by sending a DHCPRELEASE message, the server will likewise remove the A and PTR records.

THE INTERIM DNS UPDATE SCHEME

The interim DNS update scheme operates mostly according to several drafts that are being considered by the IETF and are expected to become standards, but are not yet standards, and may not be standardized exactly as currently proposed. These are:

<CENTER> draft-ietf-dhc-ddns-resolution-??.txt
draft-ietf-dhc-fqdn-option-??.txt
draft-ietf-dnsext-dhcid-rr-??.txt
</CENTER>

Because our implementation is slightly different than the standard, we will briefly document the operation of this update style here.

The first point to understand about this style of DNS update is that unlike the ad-hoc style, the DHCP server does not necessarily always update both the A and the PTR records. The FQDN option includes a flag which, when sent by the client, indicates that the client wishes to update its own A record. In that case, the server can be configured either to honor the client`s intentions or ignore them. This is done with the statement allow client-updates; or the statement ignore client-updates;. By default, client updates are allowed.

If the server is configured to allow client updates, then if the client sends a fully-qualified domain name in the FQDN option, the server will use that name the client sent in the FQDN option to update the PTR record. For example, let us say that the client is a visitor from the "radish.org" domain, whose hostname is "jschmoe". The server is for the "example.org" domain. The DHCP client indicates in the FQDN option that its FQDN is "jschmoe.radish.org.". It also indicates that it wants to update its own A record. The DHCP server therefore does not attempt to set up an A record for the client, but does set up a PTR record for the IP address that it assigns the client, pointing at jschmoe.radish.org. Once the DHCP client has an IP address, it can update its own A record, assuming that the "radish.org" DNS server will allow it to do so.

If the server is configured not to allow client updates, or if the client doesn`t want to do its own update, the server will simply choose a name for the client, possibly using the hostname supplied by the client ("jschmoe" in the previous example). It will use its own domain name for the client, just as in the ad-hoc update scheme. It will then update both the A and PTR record, using the name that it chose for the client. If the client sends a fully-qualified domain name in the fqdn option, the server uses only the leftmost part of the domain name - in the example above, "jschmoe" instead of "jschmoe.radish.org".

The other difference between the ad-hoc scheme and the interim scheme is that with the interim scheme, a method is used that allows more than one DHCP server to update the DNS database without accidentally deleting A records that shouldn`t be deleted nor failing to add A records that should be added. The scheme works as follows:

When the DHCP server issues a client a new lease, it creates a text string that is an MD5 hash over the DHCP client`s identification (see draft-ietf-dnsext-dhcid-rr-??.txt for details). The update adds an A record with the name the server chose and a TXT record containing the hashed identifier string (hashid). If this update succeeds, the server is done.

If the update fails because the A record already exists, then the DHCP server attempts to add the A record with the prerequisite that there must be a TXT record in the same name as the new A record, and that TXT record`s contents must be equal to hashid. If this update succeeds, then the client has its A record and PTR record. If it fails, then the name the client has been assigned (or requested) is in use, and can`t be used by the client. At this point the DHCP server gives up trying to do a DNS update for the client until the client chooses a new name.

The interim DNS update scheme is called interim for two reasons. First, it does not quite follow the drafts. The current versions of the drafts call for a new DHCID RRtype, but this is not yet available. The interim DNS update scheme uses a TXT record instead. Also, the existing ddns-resolution draft calls for the DHCP server to put a DHCID RR on the PTR record, but the interim update method does not do this. It is our position that this is not useful, and we are working with the author in hopes of removing it from the next version of the draft, or better understanding why it is considered useful.

In addition to these differences, the server also does not update very aggressively. Because each DNS update involves a round trip to the DNS server, there is a cost associated with doing updates even if they do not actually modify the DNS database. So the DHCP server tracks whether or not it has updated the record in the past (this information is stored on the lease) and does not attempt to update records that it thinks it has already updated.

This can lead to cases where the DHCP server adds a record, and then the record is deleted through some other mechanism, but the server never again updates the DNS because it thinks the data is already there. In this case the data can be removed from the lease through operator intervention, and once this has been done, the DNS will be updated the next time the client renews.

DYNAMIC DNS UPDATE SECURITY

When you set your DNS server up to allow updates from the DHCP server, you may be exposing it to unauthorized updates. To avoid this, you should use TSIG signatures - a method of cryptographically signing updates using a shared secret key. As long as you protect the secrecy of this key, your updates should also be secure. Note, however, that the DHCP protocol itself provides no security, and that clients can therefore provide information to the DHCP server which the DHCP server will then use in its updates, with the constraints described previously.

The DNS server must be configured to allow updates for any zone that the DHCP server will be updating. For example, let us say that clients in the sneedville.edu domain will be assigned addresses on the 10.10.17.0/24 subnet. In that case, you will need a key declaration for the TSIG key you will be using, and also two zone declarations - one for the zone containing A records that will be updates and one for the zone containing PTR records - for ISC BIND, something like this:

key DHCP_UPDATER { algorithm hmac-md5; secret pRP5FapFoJ95JEL06sv4PQ==; }; zone "example.org" { type master; file "example.org.db"; allow-update { key DHCP_UPDATER; }; }; zone "17.10.10.in-addr.arpa" { type master; file "10.10.17.db"; allow-update { key DHCP_UPDATER; }; };

You will also have to configure your DHCP server to do updates to these zones. To do so, you need to add something like this to your dhcpd.conf file:

key DHCP_UPDATER { algorithm hmac-md5; secret pRP5FapFoJ95JEL06sv4PQ==; }; zone EXAMPLE.ORG. { primary 127.0.0.1; key DHCP_UPDATER; } zone 17.127.10.in-addr.arpa. { primary 127.0.0.1; key DHCP_UPDATER; }

The primary statement specifies the IP address of the name server whose zone information is to be updated.

Note that the zone declarations have to correspond to authority records in your name server - in the above example, there must be an SOA record for "example.org." and for "17.10.10.in-addr.arpa.". For example, if there were a subdoman "foo.example.org" with no separate SOA, you could not write a zone declaration for "foo.example.org." Also keep in mind that zone names in your DHCP configuration should end in a "."; this is the preferred syntax. If you do not end your zone name in a ".", the DHCP server will figure it out. Also note that in the DHCP configuration, zone names are not encapsulated in quotes where there are in the DNS configuration.

You should choose your own secret key, of course. The ISC BIND 8 and 9 distributions come with a program for generating secret keys called dnssec-keygen. The version that comes with BIND 9 is likely to produce a substantially more random key, so we recommend you use that one even if you are not using BIND 9 as your DNS server. If you are using BIND 9`s dnssec-keygen, the above key would be created as follows:

dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER

If you are using the BIND 8 dnskeygen program, the following command will generate a key as seen above:

dnskeygen -H 128 -u -c -n DHCP_UPDATER

You may wish to enable logging of DNS updates on your DNS server. To do so, you might write a logging statement like the following:

logging { channel update_debug { file "/var/log/update-debug.log"; severity debug 3; print-category yes; print-severity yes; print-time yes; }; channel security_info { file "/var/log/named-auth.info"; severity info; print-category yes; print-severity yes; print-time yes; }; category update { update_debug; }; category security { security_info; }; };

You must create the /var/log/named-auth.info and /var/log/update-debug.log files before starting the name server. For more information on configuring ISC BIND, consult the documentation that accompanies it.

REFERENCE: EVENTS

There are three kinds of events that can happen regarding a lease, and it is possible to declare statements that occur when any of these events happen. These events are the commit event, when the server has made a commitment of a certain lease to a client, the release event, when the client has released the server from its commitment, and the expiry event, when the commitment expires.

To declare a set of statements to execute when an event happens, you must use the on statement, followed by the name of the event, followed by a series of statements to execute when the event happens, enclosed in braces. Events are used to implement DNS updates, so you should not define your own event handlers if you are using the built-in DNS update mechanism.

The built-in version of the DNS update mechanism is in a text string towards the top of server/dhcpd.c. If you want to use events for things other than DNS updates, and you also want DNS updates, you will have to start out by copying this code into your dhcpd.conf file and modifying it.

REFERENCE: DECLARATIONS

The shared-network statement

shared-network name { [ parameters ] [ declarations ] }

The shared-network statement is used to inform the DHCP server that some IP subnets actually share the same physical network. Any subnets in a shared network should be declared within a shared-network statement. Parameters specified in the shared-network statement will be used when booting clients on those subnets unless parameters provided at the subnet or host level override them. If any subnet in a shared network has addresses available for dynamic allocation, those addresses are collected into a common pool for that shared network and assigned to clients as needed. There is no way to distinguish on which subnet of a shared network a client should boot.

Name should be the name of the shared network. This name is used when printing debugging messages, so it should be descriptive for the shared network. The name may have the syntax of a valid domain name (although it will never be used as such), or it may be any arbitrary name, enclosed in quotes.

The subnet statement

subnet subnet-number netmask netmask { [ parameters ] [ declarations ] }

The subnet statement is used to provide dhcpd with enough information to tell whether or not an IP address is on that subnet. It may also be used to provide subnet-specific parameters and to specify what addresses may be dynamically allocated to clients booting on that subnet. Such addresses are specified using the range declaration.

The subnet-number should be an IP address or domain name which resolves to the subnet number of the subnet being described. The netmask should be an IP address or domain name which resolves to the subnet mask of the subnet being described. The subnet number, together with the netmask, are sufficient to determine whether any given IP address is on the specified subnet.

Although a netmask must be given with every subnet declaration, it is recommended that if there is any variance in subnet masks at a site, a subnet-mask option statement be used in each subnet declaration to set the desired subnet mask, since any subnet-mask option statement will override the subnet mask declared in the subnet statement.

The range statement

range [ dynamic-bootp ] low-address [ high-address];

For any subnet on which addresses will be assigned dynamically, there must be at least one range statement. The range statement gives the lowest and highest IP addresses in a range. All IP addresses in the range should be in the subnet in which the range statement is declared. The dynamic-bootp flag may be specified if addresses in the specified range may be dynamically assigned to BOOTP clients as well as DHCP clients. When specifying a single address, high-address can be omitted.

The host statement

host hostname { [ parameters ] [ declarations ] }

The host declaration provides a scope in which to provide configuration information about a specific client, and also provides a way to assign a client a fixed address. The host declaration provides a way for the DHCP server to identify a DHCP or BOOTP client, and also a way to assign the client a static IP address.

If it is desirable to be able to boot a DHCP or BOOTP client on more than one subnet with fixed addresses, more than one address may be specified in the fixed-address declaration, or more than one host statement may be specified.

If client-specific boot parameters must change based on the network to which the client is attached, then multiple host declaration should be used.

If a client is to be booted using a fixed address if it`s possible, but should be allocated a dynamic address otherwise, then a host declaration must be specified without a fixed-address declaration. hostname should be a name identifying the host. If a hostname option is not specified for the host, hostname is used.

Host declarations are matched to actual DHCP or BOOTP clients by matching the dhcp-client-identifier option specified in the host declaration to the one supplied by the client, or, if the host declaration or the client does not provide a dhcp-client-identifier option, by matching the hardware parameter in the host declaration to the network hardware address supplied by the client. BOOTP clients do not normally provide a dhcp-client-identifier, so the hardware address must be used for all clients that may boot using the BOOTP protocol.

Please be aware that only the dhcp-client-identifier option and the hardware address can be used to match a host declaration. For example, it is not possible to match a host declaration to a host-name option. This is because the host-name option cannot be guaranteed to be unique for any given client, whereas both the hardware address and dhcp-client-identifier option are at least theoretically guaranteed to be unique to a given client.

The group statement

group { [ parameters ] [ declarations ] }

The group statement is used simply to apply one or more parameters to a group of declarations. It can be used to group hosts, shared networks, subnets, or even other groups.

REFERENCE: ALLOW AND DENY

The allow and deny statements can be used to control the response of the DHCP server to various sorts of requests. The allow and deny keywords actually have different meanings depending on the context. In a pool context, these keywords can be used to set up access lists for address allocation pools. In other contexts, the keywords simply control general server behavior with respect to clients based on scope. In a non-pool context, the ignore keyword can be used in place of the deny keyword to prevent logging of denied requests.

ALLOW DENY AND IGNORE IN SCOPE

The following usages of allow and deny will work in any scope, although it is not recommended that they be used in pool declarations.

The unknown-clients keyword

allow unknown-clients;
deny unknown-clients;
ignore unknown-clients;

The unknown-clients flag is used to tell dhcpd whether or not to dynamically assign addresses to unknown clients. Dynamic address assignment to unknown clients is allowed by default. An unknown client is simply a client that has no host declaration.

The use of this option is now deprecated. If you are trying to restrict access on your network to known clients, you should use deny unknown-clients; inside of your address pool, as described under the heading ALLOW AND DENY WITHIN POOL DECLARAIONS.

The bootp keyword

allow bootp;
deny bootp;
ignore bootp;

The bootp flag is used to tell dhcpd whether or not to respond to bootp queries. Bootp queries are allowed by default.

This option does not satisfy the requirement of failover peers for denying dynamic bootp clients. The deny dynamic bootp clients; option should be used instead. See the ALLOW AND DENY WITHIN POOL DECLARATIONS section of this man page for more details.

The booting keyword

allow booting;
deny booting;
ignore booting;

The booting flag is used to tell dhcpd whether or not to respond to queries from a particular client. This keyword only has meaning when it appears in a host declaration. By default, booting is allowed, but if it is disabled for a particular client, then that client will not be able to get an address from the DHCP server.

The duplicates keyword

allow duplicates;
deny duplicates;

Host declarations can match client messages based on the DHCP Client Identifer option or based on the client`s network hardware type and MAC address. If the MAC address is used, the host declaration will match any client with that MAC address - even clients with different client identifiers. This doesn`t normally happen, but is possible when one computer has more than one operating system installed on it - for example, Microsoft Windows and NetBSD or Linux.

The duplicates flag tells the DHCP server that if a request is received from a client that matches the MAC address of a host declaration, any other leases matching that MAC address should be discarded by the server, even if the UID is not the same. This is a violation of the DHCP protocol, but can prevent clients whose client identifiers change regularly from holding many leases at the same time. By default, duplicates are allowed.

The declines keyword

allow declines;
deny declines;
ignore declines;

The DHCPDECLINE message is used by DHCP clients to indicate that the lease the server has offered is not valid. When the server receives a DHCPDECLINE for a particular address, it normally abandons that address, assuming that some unauthorized system is using it. Unfortunately, a malicious or buggy client can, using DHCPDECLINE messages, completely exhaust the DHCP server`s allocation pool. The server will reclaim these leases, but while the client is running through the pool, it may cause serious thrashing in the DNS, and it will also cause the DHCP server to forget old DHCP client address allocations.

The declines flag tells the DHCP server whether or not to honor DHCPDECLINE messages. If it is set to deny or ignore in a particular scope, the DHCP server will not respond to DHCPDECLINE messages.

The client-updates keyword

allow client-updates;
deny client-updates;

The client-updates flag tells the DHCP server whether or not to honor the client`s intention to do its own update of its A record. This is only relevant when doing interim DNS updates. See the documentation under the heading THE INTERIM DNS UPDATE SCHEME for details.

ALLOW AND DENY WITHIN POOL DECLARATIONS

The uses of the allow and deny keywords shown in the previous section work pretty much the same way whether the client is sending a DHCPDISCOVER or a DHCPREQUEST message - an address will be allocated to the client (either the old address it`s requesting, or a new address) and then that address will be tested to see if it`s okay to let the client have it. If the client requested it, and it`s not okay, the server will send a DHCPNAK message. Otherwise, the server will simply not respond to the client. If it is okay to give the address to the client, the server will send a DHCPACK message.

The primary motivation behind pool declarations is to have address allocation pools whose allocation policies are different. A client may be denied access to one pool, but allowed access to another pool on the same network segment. In order for this to work, access control has to be done during address allocation, not after address allocation is done.

When a DHCPREQUEST message is processed, address allocation simply consists of looking up the address the client is requesting and seeing if it`s still available for the client. If it is, then the DHCP server checks both the address pool permit lists and the relevant in-scope allow and deny statements to see if it`s okay to give the lease to the client. In the case of a DHCPDISCOVER message, the allocation process is done as described previously in the ADDRESS ALLOCATION section.

When declaring permit lists for address allocation pools, the following syntaxes are recognized following the allow or deny keywords:

known-clients;

If specified, this statement either allows or prevents allocation from this pool to any client that has a host declaration (i.e., is known). A client is known if it has a host declaration in any scope, not just the current scope.

unknown-clients;

If specified, this statement either allows or prevents allocation from this pool to any client that has no host declaration (i.e., is not known).

members of "class";

If specified, this statement either allows or prevents allocation from this pool to any client that is a member of the named class.

dynamic bootp clients;

If specified, this statement either allows or prevents allocation from this pool to any bootp client.

authenticated clients;

If specified, this statement either allows or prevents allocation from this pool to any client that has been authenticated using the DHCP authentication protocol. This is not yet supported.

unauthenticated clients;

If specified, this statement either allows or prevents allocation from this pool to any client that has not been authenticated using the DHCP authentication protocol. This is not yet supported.

all clients;

If specified, this statement either allows or prevents allocation from this pool to all clients. This can be used when you want to write a pool declaration for some reason, but hold it in reserve, or when you want to renumber your network quickly, and thus want the server to force all clients that have been allocated addresses from this pool to obtain new addresses immediately when they next renew.

REFERENCE: PARAMETERS

The always-broadcast state

dictionary

NAME

dictionary - RADIUS dictionary file

DESCRIPTION

The dictionary file resides in the radius database directory, by default /etc/raddb. It contains a list of RADIUS attributes and values, which the server uses to map between descriptive names and on-the-wire data. The names have no meaning outside of the RADIUS server itself, and are never exchanged between server and clients.

Every line starting with a hash sign (`#`) is treated as comment and ignored.

Each line of the file can contain one of the following strings

ATTRIBUTE name number type [vendor|options]

Define a RADIUS attribute name to number mapping. The name field can be any non-space text, but is usually taken from RFC2865, and other related documents. The number field is also taken from the relevant documents, for that name. The type field can be one of string, octets, ipaddr, integer, date, ifid, ipv6addr, ipv6prefix, or abinary. See the RFC`s, or the main dictionary file for a description of the various types.

The last (optional) field of an attribute definition can have either a vendor name, or options for that attribute. When a vendor name is given, the attribute is defined to be a vendor specific attribute. Alternately, the options may be the a comma-separated list of the following options:

encrypt=[1-3]

: Mark the attribute as being encrypted with one of three methods. "1" means that the attribute is encrypted with the method as defined in RFC2865 for the User-Password attribute. "2" means that the password is encrypted with the method as defined in RFC2868 for the Tunnel-Password attribute. "3" means that the attribute is encrypted as per Ascend`s definitions for the Ascend-Send-Secret attribute.

has_tag

: Mark the attribute as being permitted to have a tag, as defined in RFC2868. The purpose of the tag is to allow grouping of attributes for tunnelled users. See RFC2868 for more details.

When the server receives an encoded attribute in a RADIUS packet, it looks up that attribute by number in the dictionary, and uses the name found there for printing diagnostic and log messages.

VALUE attribute-name value-name number

Define an attribute value name to number mapping, for an attribute of type integer. The attribute-name field MUST be previously defined by an ATTRIBUTE entry. The value-name field can be any non-space text, but is usually taken from RFC2865, or other documents.. The number field is also taken from the relevant documents, for that name.

When the server receives an encoded value in a RADIUS packet, it looks up the value of that attribute by number in the dictionary, and uses the name found there for printing diagnostic and log messages.

VENDOR vendor-name number

Define a Vendor Specific Attribute encapsulation for vendor-name to number. For a list of vendor names and numbers, see http://www.iana.org/enterprise-numbers.txt.

$INCLUDE filename

Include dictionary entries from the file filename. The filename is taken as relative to the location of the file which is asking for the inclusion.

FILES

/etc/raddb/dictionary, /usr/share/freeradius/dictionary.*

distrib.pats

NAME

distrib.pats - default values for Usenet Distribution header

DESCRIPTION

The file <pathetc in inn.conf>/distrib.pats is used to determine the default value of the Distribution header. It consists of a series of lines; blank lines and lines beginning with a number sign (``#``) are ignored. All other lines consist of three fields separated by a colon:

: weight:pattern:value

The first field is the weight to assign to this match. If a newsgroup matches multiple lines, the line with the highest weight is used. This should be an arbitrary number greater than zero. Unlike other INN files, the order of lines in this file is not important.

The second field is the name of the newsgroup or a wildmat(3)-style pattern to specify a set of newsgroups. Multiple patterns are not allowed.

The third field is the value that should be used if this line is picked as the best match. It can be an empty string.

Programs such as inews(1) that process a user`s posting should consult this file, typically by using the DDxxx routines, documented in libinn(3). The intent is that all newsgroups to which an article is posted be used to index into this file, and the value with the highest weight should be used as the value of the Distribution header, if none was specified.

HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is revision 1.6, dated 1998/05/20.

ebook.eclass

NAME

ebook - easy installation of ebooks

DESCRIPTION

The ebook eclass makes writing ebuilds for ebooks a trivial task.

VARIABLES

NOTE: the following variables should be set BEFORE inheriting the ebook eclass:

DESCRIPTION: Package description. Defaults to "${P} ebook based on ebook eclass".
RDEPEND: Run-time dependencies. Defaults to ">=dev-util/devhelp-0.6".
EBOOKNAME: The name of the ebook. This variable must be set.
EBOOKVERSION: The version of the ebook. This variable must be set, even if there is no version. See the ${NOVERSION} variable below for more information.
SRC: The name of the file to download, minus the file extension. This variable defaults to ${EBOOKNAME}-${EBOOKVERSION}.
SRC_URI: The ebook URI to download. Defaults to "http://lidn.sourceforge.net/books_download/${SRC}.${EBOOKEXT}".
EBOOKEXT: The file name extension of ${SRC}. Defaults to tar.gz.
EBOOKDESTDIR: The directory inside ${DEVHELPROOT}/books/${EBOOKDIR} in which the ebook will be installed. This variable defaults to ${EBOOKNAME}-${EBOOKVERSION} or ${EBOOKNAME} if the ${NOVERSION} variable is set.
EBOOKFROMDIR: The directory in which the ebook`s HTML files are located after unpacking ${SRC_URI}. This directory is relative to ${WORKDIR}. This variable defaults to ${EBOOKNAME}-${EBOOKVERSION} or ${EBOOKNAME} if the ${NOVERSION} variable is set.
BOOKDEVHELPFILE: The file name that the ebook`s book.devhelp will be installed as. This variable defaults to ${EBOOKNAME}-${EBOOKVERSION}.devhelp or ${EBOOKNAME}.devhelp if the ${NOVERSION} variable is set.
BOOKDESTDIR: The directory in which the ebook`s HTML will be installed into. Defaults to ${EBOOKNAME}-${EBOOKVERSION} or ${EBOOKNAME} is the ${NOVERSION} variable is set.
NOVERSION: If this variable is not empty, all instances of ${EBOOKVERSION} will be removed from all variables.
DEVHELPROOT: The location of devhelp`s data directory. Defaults to usr/share/devhelp.

FUNCTIONS

NOTE: the following functions will be used as the defaults should they be omitted from the ebuild.

ebook_src_install: Installs ${BOOKDEVHELPFILE} and all HTML files into ${DEVHELPROOT}/books/${EBOOKDESTDIR}.

REPORTING BUGS

Please report bugs via http://bugs.gentoo.org/

FILES

/usr/portage/eclass/ebook.eclass

AUTHORS

Aaron Walker <ka0ttic@gentoo.org>

CVS HEADER

$Header: /var/cvsroot/gentoo-src/portage/man/ebook.eclass.5,v 1.2 2004/09/29 12:55:49 vapier Exp $

elf

NAME

elf - format of ELF executable binary files

SYNOPSIS

Fd #include <elf.h>

DESCRIPTION

The header file Aq Pa elf.h defines the format of ELF executable binary files. Amongst these files are normal executable files, relocatable object files, core files and shared libraries.

An executable file using the ELF file format consists of an ELF header, followed by a program header table or a section header table, or both. The ELF header is always at offset zero of the file. The program header table and the section header table`s offset in the file are defined in the ELF header. The two tables describe the rest of the particularities of the file.

This header file describes the above mentioned headers as C structures and also includes structures for dynamic sections, relocation sections and symbol tables.

The following types are used for N-bit architectures (N=32,64, ElfN stands for Elf32 or Elf64, uintN_t stands for uint32_t or uint64_t):

ElfN_Addr Unsigned program address, uintN_t ElfN_Off Unsigned file offset, uintN_t ElfN_Section Unsigned section index, uint16_t ElfN_Versym Unsigned version symbol information, uint16_t Elf_Byte unsigned char ElfN_Half uint16_t ElfN_Sword int32_t ElfN_Word uint32_t ElfN_Sxword int64_t ElfN_Xword uint64_t

(Note: The *BSD terminology is a bit different. There Elf64_Half is twice as large as Elf32_Half, and Elf64Quarter is used for uint16_t. In order to avoid confusion these types are replaced by explicit ones in the below.)

All data structures that the file format defines follow the ``natural`` size and alignment guidelines for the relevant class. If necessary, data structures contain explicit padding to ensure 4-byte alignment for 4-byte objects, to force structure sizes to a multiple of 4, etc.

The ELF header is described by the type Elf32_Ehdr or Elf64_Ehdr:

#define EI_NIDENT 16 typedef struct { unsigned char e_ident[EI_NIDENT]; uint16_t e_type; uint16_t e_machine; uint32_t e_version; ElfN_Addr e_entry; ElfN_Off e_phoff; ElfN_Off e_shoff; uint32_t e_flags; uint16_t e_ehsize; uint16_t e_phentsize; uint16_t e_phnum; uint16_t e_shentsize; uint16_t e_shnum; uint16_t e_shstrndx; } ElfN_Ehdr;

The fields have the following meanings:

e_ident

This array of bytes specifies to interpret the file, independent of the processor or the file`s remaining contents. Within this array everything is named by macros, which start with the prefix EI_ and may contain values which start with the prefix ELF The following macros are defined:

EI_MAG0

The first byte of the magic number. It must be filled with ELFMAG0 (0: 0x7f)

EI_MAG1

The second byte of the magic number. It must be filled with ELFMAG1 (1: `E`)

EI_MAG2

The third byte of the magic number. It must be filled with ELFMAG2 (2: `L`)

EI_MAG3

The fourth byte of the magic number. It must be filled with ELFMAG3 (3: `F`)

EI_CLASS

The fifth byte identifies the architecture for this binary:

ELFCLASSNONE: This class is invalid.
ELFCLASS32: This defines the 32-bit architecture. It supports machines with files and virtual address spaces up to 4 Gigabytes.
ELFCLASS64: This defines the 64-bit architecture.

EI_DATA

The sixth byte specifies the data encoding of the processor-specific data in the file. Currently these encodings are supported:

ELFDATANONE: Unknown data format.
ELFDATA2LSB: Two`s complement, little-endian.
ELFDATA2MSB: Two`s complement, big-endian.

EI_VERSION

The version number of the ELF specification:

EV_NONE: Invalid version.
EV_CURRENT: Current version.

EI_OSABI

This byte identifies the operating system and ABI to which the object is targeted. Some fields in other ELF structures have flags and values that have platform specific meanings; the interpretation of those fields is determined by the value of this byte. E.g.:

ELFOSABI_SYSV: UNIX System V ABI.
ELFOSABI_HPUX: HP-UX ABI.
ELFOSABI_NETBSD: NetBSD ABI.
ELFOSABI_LINUX: Linux ABI.
ELFOSABI_SOLARIS: Solaris ABI.
ELFOSABI_IRIX: IRIX ABI.
ELFOSABI_FREEBSD: FreeBSD ABI.
ELFOSABI_TRU64: TRU64 UNIX ABI.
ELFOSABI_ARM: ARM architecture ABI.
ELFOSABI_STANDALONE: Stand-alone (embedded) ABI.

EI_ABIVERSION

This byte identifies the version of the ABI to which the object is targeted. This field is used to distinguish among incompatible versions of an ABI. The interpretation of this version number is dependent on the ABI identified by the EI_OSABI field. Applications conforming to this specification use the value 0.

EI_PAD

Start of padding. These bytes are reserved and set to zero. Programs which read them should ignore them. The value for EI_PAD will change in the future if currently unused bytes are given meanings.

EI_BRAND

Start of architecture identification.

EI_NIDENT

The size of the e_ident array.

e_type

This member of the structure identifies the object file type:

ET_NONE: An unknown type.
ET_REL: A relocatable file.
ET_EXEC: An executable file.
ET_DYN: A shared object.
ET_CORE: A core file.

e_machine

This member specifies the required architecture for an individual file. E.g.:

EM_NONE: An unknown machine.
EM_M32: AT&T WE 32100.
EM_SPARC: Sun Microsystems SPARC.
EM_386: Intel 80386.
EM_68K: Motorola 68000.
EM_88K: Motorola 88000.
EM_860: Intel 80860.
EM_MIPS: MIPS RS3000 (big-endian only).
EM_PARISC: HPPA.
EM_SPARC32PLUS: SPARC with enhanced instruction set.
EM_PPC: PowerPC.
EM_SPARCV9: SPARC v9 64-bit.
EM_VAX: DEC Vax.

e_version

This member identifies the file version:

EV_NONE: Invalid version.
EV_CURRENT: Current version.

e_entry

This member gives the virtual address to which the system first transfers control, thus starting the process. If the file has no associated entry point, this member holds zero.

e_phoff

This member holds the program header table`s file offset in bytes. If the file has no program header table, this member holds zero.

e_shoff

This member holds the section header table`s file offset in bytes. If the file has no section header table this member holds zero.

e_flags

This member holds processor-specific flags associated with the file. Flag names take the form EF_`machine_flag`. Currently no flags have been defined.

e_ehsize

This member holds the ELF header`s size in bytes.

e_phentsize

This member holds the size in bytes of one entry in the file`s program header table; all entries are the same size.

e_phnum

This member holds the number of entries in the program header table. Thus the product of e_phentsize and e_phnum gives the table`s size in bytes. If a file has no program header, e_phnum holds the value zero.

e_shentsize

This member holds a sections header`s size in bytes. A section header is one entry in the section header table; all entries are the same size.

e_shnum

This member holds the number of entries in the section header table. Thus the product of e_shentsize and e_shnum gives the section header table`s size in bytes. If a file has no section header table, e_shnum holds the value of zero.

e_shstrndx

This member holds the section header table index of the entry associated with the section name string table. If the file has no section name string table, this member holds the value SHN_UNDEF

SHN_UNDEF: This value marks an undefined, missing, irrelevant, or otherwise meaningless section reference. For example, a symbol ``defined`` relative to section number SHN_UNDEF is an undefined symbol.
SHN_LORESERVE: This value specifies the lower bound of the range of reserved indices.
SHN_LOPROC: Values greater than or equal to SHN_HIPROC are reserved for processor-specific semantics.
SHN_HIPROC: Values less than or equal to SHN_LOPROC are reserved for processor-specific semantics.
SHN_ABS: This value specifies absolute values for the corresponding reference. For example, symbols defined relative to section number SHN_ABS have absolute values and are not affected by relocation.
SHN_COMMON: Symbols defined relative to this section are common symbols, such as Fortran COMMON or unallocated C external variables.
SHN_HIRESERVE: This value specifies the upper bound of the range of reserved indices between SHN_LORESERVE and SHN_HIRESERVE inclusive; the values do not reference the section header table. That is, the section header table does not contain entries for the reserved indices.

An executable or shared object file`s program header table is an array of structures, each describing a segment or other information the system needs to prepare the program for execution. An object file segment contains one or more sections Program headers are meaningful only for executable and shared object files. A file specifies its own program header size with the ELF header`s e_phentsize and e_phnum members. The ELF program header is described by the type Elf32_Phdr or Elf64_Phdr depending on the architecture:

typedef struct { uint32_t p_type; Elf32_Off p_offset; Elf32_Addr p_vaddr; Elf32_Addr p_paddr; uint32_t p_filesz; uint32_t p_memsz; uint32_t p_flags; uint32_t p_align; } Elf32_Phdr;

typedef struct { uint32_t p_type; uint32_t p_flags; Elf64_Off p_offset; Elf64_Addr p_vaddr; Elf64_Addr p_paddr; uint64_t p_filesz; uint64_t p_memsz; uint64_t p_align; } Elf64_Phdr;

The main difference between the 32-bit and the 64-bit program header lies in the location of the p_flags member in the total struct.

p_type

This member of the Phdr struct tells what kind of segment this array element describes or how to interpret the array element`s information.

PT_NULL: The array element is unused and the other members` values are undefined. This lets the program header have ignored entries.
PT_LOAD: The array element specifies a loadable segment, described by p_filesz and p_memsz The bytes from the file are mapped to the beginning of the memory segment. If the segment`s memory size (p_memsz ) is larger than the file size (p_filesz ) the ``extra`` bytes are defined to hold the value 0 and to follow the segment`s initialized area. The file size may not be larger than the memory size. Loadable segment entries in the program header table appear in ascending order, sorted on the p_vaddr member.
PT_DYNAMIC: The array element specifies dynamic linking information.
PT_INTERP: The array element specifies the location and size of a null-terminated path name to invoke as an interpreter. This segment type is meaningful only for executable files (though it may occur for shared objects). However it may not occur more than once in a file. If it is present, it must precede any loadable segment entry.
PT_NOTE: The array element specifies the location and size for auxiliary information.
PT_SHLIB: This segment type is reserved but has unspecified semantics. Programs that contain an array element of this type do not conform to the ABI.
PT_PHDR: The array element, if present, specifies the location and size of the program header table itself, both in the file and in the memory image of the program. This segment type may not occur more than once in a file. Moreover, it may only occur if the program header table is part of the memory image of the program. If it is present, it must precede any loadable segment entry.
PT_LOPROC: Values greater than or equal to PT_HIPROC are reserved for processor-specific semantics.
PT_HIPROC: Values less than or equal to PT_LOPROC are reserved for processor-specific semantics.

p_offset

This member holds the offset from the beginning of the file at which the first byte of the segment resides.

p_vaddr

This member holds the virtual address at which the first byte of the segment resides in memory.

p_paddr

On systems for which physical addressing is relevant, this member is reserved for the segment`s physical address. Under BSD this member is not used and must be zero.

p_filesz

This member holds the number of bytes in the file image of the segment. It may be zero.

p_memsz

This member holds the number of bytes in the memory image of the segment. It may be zero.

p_flags

This member holds flags relevant to the segment:

PF_X: An executable segment.
PF_W: A writable segment.
PF_R: A readable segment.

A text segment commonly has the flags PF_X and PF_R A data segment commonly has PF_X PF_W and PF_R

p_align

This member holds the value to which the segments are aligned in memory and in the file. Loadable process segments must have congruent values for p_vaddr and p_offset modulo the page size. Values of zero and one mean no alignment is required. Otherwise, p_align should be a positive, integral power of two, and p_vaddr should equal p_offset modulo p_align

A file`s section header table lets one locate all the file`s sections. The section header table is an array of Elf32_Shdr or Elf64_Shdr structures. The ELF header`s e_shoff member gives the byte offset from the beginning of the file to the section header table. e_shnum holds the number of entries the section header table contains. e_shentsize holds the size in bytes of each entry.

A section header table index is a subscript into this array. Some section header table indices are reserved. An object file does not have sections for these special indices:

SHN_UNDEF: This value marks an undefined, missing, irrelevant or otherwise meaningless section reference.
SHN_LORESERVE: This value specifies the lower bound of the range of reserved indices.
SHN_LOPROC: Values greater than or equal to SHN_HIPROC are reserved for processor-specific semantics.
SHN_HIPROC: Values less than or equal to SHN_LOPROC are reserved for processor-specific semantics.
SHN_ABS: This value specifies the absolute value for the corresponding reference. For example, a symbol defined relative to section number SHN_ABS has an absolute value and is not affected by relocation.
SHN_COMMON: Symbols defined relative to this section are common symbols, such as FORTRAN COMMON or unallocated C external variables.
SHN_HIRESERVE: This value specifies the upper bound of the range of reserved indices. The system reserves indices between SHN_LORESERVE and SHN_HIRESERVE inclusive. The section header table does not contain entries for the reserved indices.

The section header has the following structure:

typedef struct { uint32_t sh_name; uint32_t sh_type; uint32_t sh_flags; Elf32_Addr sh_addr; Elf32_Off sh_offset; uint32_t sh_size; uint32_t sh_link; uint32_t sh_info; uint32_t sh_addralign; uint32_t sh_entsize; } Elf32_Shdr;

typedef struct { uint32_t sh_name; uint32_t sh_type; uint64_t sh_flags; Elf64_Addr sh_addr; Elf64_Off sh_offset; uint64_t sh_size; uint32_t sh_link; uint32_t sh_info; uint64_t sh_addralign; uint64_t sh_entsize; } Elf64_Shdr;

sh_name

This member specifies the name of the section. Its value is an index into the section header string table section, giving the location of a null-terminated string.

sh_type

This member categorizes the section`s contents and semantics.

SHT_NULL: This value marks the section header as inactive. It does not have an associated section. Other members of the section header have undefined values.
SHT_PROGBITS: This section holds information defined by the program, whose format and meaning are determined solely by the program.
SHT_SYMTAB: This section holds a symbol table. Typically, SHT_SYMTAB provides symbols for link editing, though it may also be used for dynamic linking. As a complete symbol table, it may contain many symbols unnecessary for dynamic linking. An object file can also contain a SHN_DYNSYM section.
SHT_STRTAB: This section holds a string table. An object file may have multiple string table sections.
SHT_RELA: This section holds relocation entries with explicit addends, such as type Elf32_Rela for the 32-bit class of object files. An object may have multiple relocation sections.
SHT_HASH: This section holds a symbol hash table. An object participating in dynamic linking must contain a symbol hash table. An object file may have only one hash table.
SHT_DYNAMIC: This section holds information for dynamic linking. An object file may have only one dynamic section.
SHT_NOTE: This section holds information that marks the file in some way.
SHT_NOBITS: A section of this type occupies no space in the file but otherwise resembles SHN_PROGBITS Although this section contains no bytes, the sh_offset member contains the conceptual file offset.
SHT_REL: This section holds relocation offsets without explicit addends, such as type Elf32_Rel for the 32-bit class of object files. An object file may have multiple relocation sections.
SHT_SHLIB: This section is reserved but has unspecified semantics.
SHT_DYNSYM: This section holds a minimal set of dynamic linking symbols. An object file can also contain a SHN_SYMTAB section.
SHT_LOPROC: This value up to and including SHT_HIPROC is reserved for processor-specific semantics.
SHT_HIPROC: This value down to and including SHT_LOPROC is reserved for processor-specific semantics.
SHT_LOUSER: This value specifies the lower bound of the range of indices reserved for application programs.
SHT_HIUSER: This value specifies the upper bound of the range of indices reserved for application programs. Section types between SHT_LOUSER and SHT_HIUSER may be used by the application, without conflicting with current or future system-defined section types.

sh_flags

Sections support one-bit flags that describe miscellaneous attributes. If a flag bit is set in sh_flags the attribute is ``on`` for the section. Otherwise, the attribute is ``off`` or does not apply. Undefined attributes are set to zero.

SHF_WRITE: This section contains data that should be writable during process execution.
SHF_ALLOC: This section occupies memory during process execution. Some control sections do not reside in the memory image of an object file. This attribute is off for those sections.
SHF_EXECINSTR: This section contains executable machine instructions.
SHF_MASKPROC: All bits included in this mask are reserved for processor-specific semantics.

sh_addr

If this section appears in the memory image of a process, this member holds the address at which the section`s first byte should reside. Otherwise, the member contains zero.

sh_offset

This member`s value holds the byte offset from the beginning of the file to the first byte in the section. One section type, SHT_NOBITS occupies no space in the file, and its sh_offset member locates the conceptual placement in the file.

sh_size

This member holds the section`s size in bytes. Unless the section type is SHT_NOBITS the section occupies sh_size bytes in the file. A section of type SHT_NOBITS may have a non-zero size, but it occupies no space in the file.

sh_link

This member holds a section header table index link, whose interpretation depends on the section type.

sh_info

This member holds extra information, whose interpretation depends on the section type.

sh_addralign

Some sections have address alignment constraints. If a section holds a doubleword, the system must ensure doubleword alignment for the entire section. That is, the value of sh_addr must be congruent to zero, modulo the value of sh_addralign Only zero and positive integral powers of two are allowed. Values of zero or one mean the section has no alignment constraints.

sh_entsize

Some sections hold a table of fixed-sized entries, such as a symbol table. For such a section, this member gives the size in bytes for each entry. This member contains zero if the section does not hold a table of fixed-size entries.

Various sections hold program and control information:

.bss: This section holds uninitialized data that contributes to the program`s memory image. By definition, the system initializes the data with zeros when the program begins to run. This section is of type SHT_NOBITS The attribute types are SHF_ALLOC and SHF_WRITE
.comment: This section holds version control information. This section is of type SHT_PROGBITS No attribute types are used.
.ctors: This section holds initialized pointers to the C++ constructor functions. This section is of type SHT_PROGBITS The attribute types are SHF_ALLOC and SHF_WRITE
.data: This section holds initialized data that contribute to the program`s memory image. This section is of type SHT_PROGBITS The attribute types are SHF_ALLOC and SHF_WRITE
.data1: This section holds initialized data that contribute to the program`s memory image. This section is of type SHT_PROGBITS The attribute types are SHF_ALLOC and SHF_WRITE
.debug: This section holds information for symbolic debugging. The contents are unspecified. This section is of type SHT_PROGBITS No attribute types are used.
.dtors: This section holds initialized pointers to the C++ destructor functions. This section is of type SHT_PROGBITS The attribute types are SHF_ALLOC and SHF_WRITE
.dynamic: This section holds dynamic linking information. The section`s attributes will include the SHF_ALLOC bit. Whether the SHF_WRITE bit is set is processor-specific. This section is of type SHT_DYNAMIC See the attributes above.
.dynstr: This section holds strings needed for dynamic linking, most commonly the strings that represent the names associated with symbol table entries. This section is of type SHT_STRTAB The attribute type used is SHF_ALLOC
.dynsym: This section holds the dynamic linking symbol table. This section is of type SHT_DYNSYM The attribute used is SHF_ALLOC
.fini: This section holds executable instructions that contribute to the process termination code. When a program exits normally the system arranges to execute the code in this section. This section is of type SHT_PROGBITS The attributes used are SHF_ALLOC and SHF_EXECINSTR
.got: This section holds the global offset table. This section is of type SHT_PROGBITS The attributes are processor-specific.
.hash: This section holds a symbol hash table. This section is of type SHT_HASH The attribute used is SHF_ALLOC
.init: This section holds executable instructions that contribute to the process initialization code. When a program starts to run the system arranges to execute the code in this section before calling the main program entry point. This section is of type SHT_PROGBITS The attributes used are SHF_ALLOC and SHF_EXECINSTR
.interp: This section holds the pathname of a program interpreter. If the file has a loadable segment that includes the section, the section`s attributes will include the SHF_ALLOC bit. Otherwise, that bit will be off. This section is of type SHT_PROGBITS
.line: This section holds line number information for symbolic debugging, which describes the correspondence between the program source and the machine code. The contents are unspecified. This section is of type SHT_PROGBITS No attribute types are used.
.note: This section holds information in the ``Note Section`` format described below. This section is of type SHT_NOTE No attribute types are used. Ox native executables usually contain a .note.openbsd.ident section to identify themselves, for the kernel to bypass any compatibility ELF binary emulation tests when loading the file.
.plt: This section holds the procedure linkage table. This section is of type SHT_PROGBITS The attributes are processor-specific.
.relNAME: This section holds relocation information as described below. If the file has a loadable segment that includes relocation, the section`s attributes will include the SHF_ALLOC bit. Otherwise the bit will be off. By convention, ``NAME`` is supplied by the section to which the relocations apply. Thus a relocation section for .text normally would have the name .rel.text This section is of type SHT_REL
.relaNAME: This section holds relocation information as described below. If the file has a loadable segment that includes relocation, the section`s attributes will include the SHF_ALLOC bit. Otherwise the bit will be off. By convention, ``NAME`` is supplied by the section to which the relocations apply. Thus a relocation section for .text normally would have the name .rela.text This section is of type SHT_RELA
.rodata: This section holds read-only data that typically contributes to a non-writable segment in the process image. This section is of type SHT_PROGBITS The attribute used is SHF_ALLOC
.rodata1: This section holds read-only data that typically contributes to a non-writable segment in the process image. This section is of type SHT_PROGBITS The attribute used is SHF_ALLOC
.shstrtab: This section holds section names. This section is of type SHT_STRTAB No attribute types are used.
.strtab: This section holds strings, most commonly the strings that represent the names associated with symbol table entries. If the file has a loadable segment that includes the symbol string table, the section`s attributes will include the SHF_ALLOC bit. Otherwise the bit will be off. This section is of type SHT_STRTAB
.symtab: This section holds a symbol table. If the file has a loadable segment that includes the symbol table, the section`s attributes will include the SHF_ALLOC bit. Otherwise the bit will be off. This section is of type SHT_SYMTAB
.text: This section holds the ``text`` or executable instructions, of a program. This section is of type SHT_PROGBITS The attributes used are SHF_ALLOC and SHF_EXECINSTR

String table sections hold null-terminated character sequences, commonly called strings. The object file uses these strings to represent symbol and section names. One references a string as an index into the string table section. The first byte, which is index zero, is defined to hold a null character. Similarly, a string table`s last byte is defined to hold a null character, ensuring null termination for all strings.

An object file`s symbol table holds information needed to locate and relocate a program`s symbolic definitions and references. A symbol table index is a subscript into this array.

typedef struct { uint32_t st_name; Elf32_Addr st_value; uint32_t st_size; unsigned char st_info; unsigned char st_other; uint16_t st_shndx; } Elf32_Sym;

typedef struct { uint32_t st_name; unsigned char st_info; unsigned char st_other; uint16_t st_shndx; Elf64_Addr st_value; uint64_t st_size; } Elf64_Sym;

st_name

This member holds an index into the object file`s symbol string table, which holds character representations of the symbol names. If the value is non-zero, it represents a string table index that gives the symbol name. Otherwise, the symbol table has no name.

st_value

This member gives the value of the associated symbol.

st_size

Many symbols have associated sizes. This member holds zero if the symbol has no size or an unknown size.

st_info

This member specifies the symbol`s type and binding attributes:

STT_NOTYPE: The symbol`s type is not defined.
STT_OBJECT: The symbol is associated with a data object.
STT_FUNC: The symbol is associated with a function or other executable code.
STT_SECTION: The symbol is associated with a section. Symbol table entries of this type exist primarily for relocation and normally have STB_LOCAL bindings.
STT_FILE: By convention, the symbol`s name gives the name of the source file associated with the object file. A file symbol has STB_LOCAL bindings, its section index is SHN_ABS and it precedes the other STB_LOCAL symbols of the file, if it is present.
STT_LOPROC: This value up to and including STT_HIPROC is reserved for processor-specific semantics.
STT_HIPROC: This value down to and including STT_LOPROC is reserved for processor-specific semantics.

STB_LOCAL

Local symbols are not visible outside the object file containing their definition. Local symbols of the same name may exist in multiple files without interfering with each other.

STB_GLOBAL

Global symbols are visible to all object files being combined. One file`s definition of a global symbol will satisfy another file`s undefined reference to the same symbol.

STB_WEAK

Weak symbols resemble global symbols, but their definitions have lower precedence.

STB_LOPROC

This value up to and including STB_HIPROC is reserved for processor-specific semantics.

STB_HIPROC

This value down to and including STB_LOPROC is reserved for processor-specific semantics.

There are macros for packing and unpacking the binding and type fields:

Fn ELF32_ST_BIND info: or Fn ELF64_ST_BIND info extract a binding from an st_info value.
Fn ELF64_ST_TYPE info: or Fn ELF32_ST_TYPE info extract a type from an st_info value.
Fn ELF32_ST_INFO bind type: or Fn ELF64_ST_INFO bind type convert a binding and a type into an st_info value.

st_other

This member currently holds zero and has no defined meaning.

st_shndx

Every symbol table entry is ``defined`` in relation to some section. This member holds the relevant section header table index.

Relocation is the process of connecting symbolic references with symbolic definitions. Relocatable files must have information that describes how to modify their section contents, thus allowing executable and shared object files to hold the right information for a process` program image. Relocation entries are these data.

Relocation structures that do not need an addend:

typedef struct { Elf32_Addr r_offset; uint32_t r_info; } Elf32_Rel;

typedef struct { Elf64_Addr r_offset; uint64_t r_info; } Elf64_Rel;

Relocation structures that need an addend:

typedef struct { Elf32_Addr r_offset; uint32_t r_info; int32_t r_addend; } Elf32_Rela;

typedef struct { Elf64_Addr r_offset; uint64_t r_info; int64_t r_addend; } Elf64_Rela;

r_offset: This member gives the location at which to apply the relocation action. For a relocatable file, the value is the byte offset from the beginning of the section to the storage unit affected by the relocation. For an executable file or shared object, the value is the virtual address of the storage unit affected by the relocation.
r_info: This member gives both the symbol table index with respect to which the relocation must be made and the type of relocation to apply. Relocation types are processor-specific. When the text refers to a relocation entry`s relocation type or symbol table index, it means the result of applying ELF_[32|64]_R_TYPE or ELF[32|64]_R_SYM respectively, to the entry`s r_info member.
r_addend: This member specifies a constant addend used to compute the value to be stored into the relocatable field.

HISTORY

Ox ELF support first appeared in Ox 1.2 , although not all supported platforms use it as the native binary file format. ELF in itself first appeared in AT&T System V . The ELF format is an adopted standard.

AUTHORS

The original version of this manual page was written by An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org with inspiration from BSDi`s Bs x elf manpage.

elinkskeys

NAME

elinkskeys - keybindings for ELinks

DESCRIPTION

Key bindings for elinks should be placed in a file called ~/.elinks/elinks.conf. Note that any information regarding their format/structure may not be up-to-date. If you will discover that, please feed us with a patch.

Key binding statements are of the form:

bind "keymap" "keystroke" = "action"

where:

keymap: is main, edit, or menu.
keystroke: is a case sensitive key, which you can prefix with Ctrl- or Alt-. Ctrl- must be followed by an uppercase key. See below for a list of valid keys.
action: is what the key should do. The actions available are dependent on the keymap, and are listed separately below.

All words/strings may all be quoted "like so". Backslashes are escape characters, even if not between quotes. Lines beginning with a hash character (#) are comments.

Keys can be unbound just by binding them to "none" action. It may be of use if you accidentally type a key often.

KEYS

Valid keys are: alphanumeric characters, punctuation, Enter, Backspace, Tab, Escape, Left, Right, Up, Down, Insert, Delete, Home, End, PageUp, PageDown, F1 to F12.

Some keys will need to be quoted or escaped. For example, space can be written as " " (quote space quote), and the quote itself as " (backslash quote). Backslash can be written as \ (double backslash).

MAIN KEYMAP ACTIONS

The main keymap is used for general browsing.

add-bookmark: Open a dialog box to add a new bookmark.
back: Return to the previous page.
bookmark-manager: Open the bookmark manager dialog.
cookies-load: Reload cookies file.
copy-clipboard: Copy the current link to the clipboard.
document-info: Show some information about the current page.
down: Move cursor downwards.
download: Start downloading the current link.
end: Go to the end of the page.
enter: Follow the current link.
file-menu: Open the File menu.
find-next: Find the next occurrence of the current search text.
find-next-back: Find the next occurrence of the current search text, in reverse.
goto-url: Open a "Go to URL" dialog box.
goto-url-current: Open a "Go to URL" dialog box containing the current URL.
goto-url-current-link: Open a "Go to URL" dialog box containing the current link.
header-info: Show the current page header information.
home: Go to the start of the page.
link-menu: Activate the contextual link menu.
lua-console: Open a Lua Console dialog box. Only available if Lua scripting support has been compiled in (Links-Lua and ELinks).
menu: Activate the menu.
next-frame: Move to the next frame.
open-new-window: Open a new instace of ELinks in a new window.
open-link-in-new-window: Open the current link in a new instance of ELinks in a new window.
page-down: Move downwards by a page.
page-up: Move upwards by a page.
paste-clipboard: Paste text from the clipboard.
previous-frame: Move to the previous frame.
quit: Open a quit confirmation dialog box.
really-quit: Quit without confirmation.
reload: Reload the current page.
scroll-down: Scroll the viewing window downwards.
scroll-left: Scroll the viewing window to the left.
scroll-right: Scroll the viewing window to the right.
scroll-up: Scroll the viewing window upwards.
search: Search for some text.
search-back: Search for some text, in reverse.
toggle-display-images: Toggle whether to display links to images.
toggle-display-tables: Toggle whether to render tables.
toggle-html-plain: Toggles between rendering the current page as HTML or plaintext.
unback: Go forwards in unhistory.
up: Move cursor upwards.
view-image: View the image under the cursor.
zoom-frame: Show the current frame using the entire screen.

EDIT KEYMAP ACTIONS

The edit keymap is used for editing text fields.

up
down
left
right
home
end
backspace
delete
kill-to-bol: Delete text from cursor to beginning of line.
kill-to-eol: Delete text from cursor to end of line
auto-complete
enter
copy-clipboard
cut-clipboard
paste-clipboard
edit: Edit the current textarea in an external text editor.

MENU KEYMAP ACTIONS

The menu keymap is used for navigating menus.

left
right
up
down
home
end
page-up
page-down

NAVIGATION KEYS

You may prefix each of these keys with a number, telling its repeat count (how many times to do it). You can also re-bind keys, see elinkskeys(5) for documentation and a more complete list of keys bound by default.

PGDN: page down
Space: page down
PGUP: page up
b: page up
B: page up
DOWN: next link/down
UP: prev link/up
^INS: copy to clipboard
^C: copy to clipboard
INS: scroll up
^P: scroll up
DEL: scroll down
^N: scroll down
[: scroll left
]: scroll right
HOME: home
END: end of page
RIGHT: enter link/press button
ENTER: enter link/press button
LEFT: go back
d: download link
D: download link
F4: edit textarea in external editor (broken)
^T: edit textarea in external editor (broken)
/: search in the page
?: search back in the page
n: find next match
N: find next match backwards
f: zoom actual frame
F: zoom actual frame
^R: reload page
g: go to URL
G: go to the current URL
a: add a new bookmark
A: add a new bookmark
s: bookmark manager
S: bookmark manager
^K: reload cookies from ~/.elinks/cookies
q: quit
Q: quit
=: document information
|: header information
: toggle HTML source/rendered view
*: toggle display of images
TAB: next frame
ESC: menu/escape
F9: menu
F10: file menu

EDITING KEYS

The following keys can be used while editing a line/jumping to a URL:

RIGHT: move right
LEFT: move left
HOME: jump to the beginning
^A: jump to the beginning
END: jump to the end
^E: jump to the end
^INS: copy to clipboard
^B: copy to clipboard
^X: cut to clipboard
^V: paste from clipboard
ENTER: enter line
BACKSPACE: delete back character
^H: delete back character
DEL: delete character
^D: delete character
^U: delete from beginning of the line
^K: delete to the end of the line
^W: auto complete line

DEFAULT BINDINGS

The default bindings are shown below. Any bindings in elinks.conf will override these. This list is given as an example, and may not be up to date.

bind "main" "v" = "view-image" bind "main" "l" = "jump-to-link" bind "main" "L" = "link-menu" bind "main" "F10" = "file-menu" bind "main" "F9" = "menu" bind "main" "Escape" = "menu" bind "main" "Tab" = "next-frame" bind "main" "*" = "toggle-display-images" bind "main" "." = "toggle-numbered-links" bind "main" "\" = "toggle-html-plain" bind "main" "<" = "tab-prev" bind "main" ">" = "tab-next" bind "main" "c" = "tab-close" bind "main" "|" = "header-info" bind "main" "=" = "document-info" bind "main" "Q" = "really-quit" bind "main" "q" = "quit" bind "main" "Ctrl-K" = "cookies-load" bind "main" "k" = "keybinding-manager" bind "main" "o" = "options-manager" bind "main" "h" = "history-manager" bind "main" "S" = "bookmark-manager" bind "main" "s" = "bookmark-manager" bind "main" "A" = "add-bookmark-link" bind "main" "a" = "add-bookmark" bind "main" "M" = "goto-url-home" bind "main" "m" = "goto-url-home" bind "main" "H" = "goto-url-home" bind "main" "G" = "goto-url-current" bind "main" "g" = "goto-url" bind "main" "E" = "goto-url-current-link" bind "main" "Ctrl-R" = "reload" bind "main" "F" = "zoom-frame" bind "main" "f" = "zoom-frame" bind "main" "N" = "find-next-back" bind "main" "n" = "find-next" bind "main" "?" = "search-back" bind "main" "/" = "search" bind "main" "z" = "abort-connection" bind "main" "R" = "resume-download" bind "main" "r" = "resume-download" bind "main" "D" = "download" bind "main" "d" = "download" bind "main" "U" = "unback" bind "main" "u" = "unback" bind "main" "Left" = "back" bind "main" "x" = "enter-reload" bind "main" "Ctrl-Enter" = "enter-reload" bind "main" "Ctrl-Right" = "enter-reload" bind "main" "Enter" = "enter" bind "main" "Right" = "enter" bind "main" "Ctrl-E" = "end" bind "main" "End" = "end" bind "main" "Ctrl-A" = "home" bind "main" "Home" = "home" bind "main" "}" = "scroll-right" bind "main" "{" = "scroll-left" bind "main" "]" = "scroll-right" bind "main" "[" = "scroll-left" bind "main" "Ctrl-N" = "scroll-down" bind "main" "Delete" = "scroll-down" bind "main" "Ctrl-P" = "scroll-up" bind "main" "Insert" = "scroll-up" bind "main" "Ctrl-C" = "copy-clipboard" bind "main" "Ctrl-Insert" = "copy-clipboard" bind "main" "Up" = "up" bind "main" "Down" = "down" bind "main" "Ctrl-B" = "page-up" bind "main" "B" = "page-up" bind "main" "b" = "page-up" bind "main" "PageUp" = "page-up" bind "main" "Ctrl-F" = "page-down" bind "main" " " = "page-down" bind "main" "PageDown" = "page-down" bind "edit" "Ctrl-R" = "auto-complete-unambiguous" bind "edit" "Ctrl-W" = "auto-complete" bind "edit" "Ctrl-K" = "kill-to-eol" bind "edit" "Ctrl-U" = "kill-to-bol" bind "edit" "Ctrl-D" = "delete" bind "edit" "Delete" = "delete" bind "edit" "Ctrl-H" = "backspace" bind "edit" "Backspace" = "backspace" bind "edit" "Enter" = "enter" bind "edit" "Ctrl-V" = "paste-clipboard" bind "edit" "Ctrl-X" = "cut-clipboard" bind "edit" "Ctrl-C" = "copy-clipboard" bind "edit" "Ctrl-Insert" = "copy-clipboard" bind "edit" "Ctrl-T" = "edit" bind "edit" "F4" = "edit" bind "edit" "Ctrl-E" = "end" bind "edit" "End" = "end" bind "edit" "Down" = "down" bind "edit" "Up" = "up" bind "edit" "Ctrl-A" = "home" bind "edit" "Home" = "home" bind "edit" "Right" = "right" bind "edit" "Left" = "left" bind "menu" "Ctrl-B" = "page-up" bind "menu" "PageUp" = "page-up" bind "menu" "Ctrl-F" = "page-down" bind "menu" "PageDown" = "page-down" bind "menu" "Enter" = "enter" bind "menu" "Ctrl-E" = "end" bind "menu" "End" = "end" bind "menu" "Down" = "down" bind "menu" "Up" = "up" bind "menu" "Ctrl-A" = "home" bind "menu" "Home" = "home" bind "menu" "Right" = "right" bind "menu" "Left" = "left" # ELinks with Lua support bind "main" "," = "lua-console"

AUTHOR

This manual page was finally written by Peter Wang (one and a half years after writing the binding code), using excerpts by David Mediavilla. You can thank Petr Baudis for the subtle requests for documentation. Updated by Zas. Moved to docbook format and cleaned up by Jonas.

ethers

NAME ethers - Ethernet address to IP number database

DESCRIPTION /etc/ethers contains 48 bit Ethernet addresses and their corresponding

IP numbers, one line for each IP number:

: Ethernet-address IP-number

The two items are separated by any number of SPACE and/or TAB char acters. A # at the beginning of a line starts a comment which extends to the end of the line. The Ethernet-address is written as x:x:x:x:x:x, where x is a hexadecimal number between 0 and ff which represents one byte of the address, which is in network byte order (big-endian). The IP-number may be a hostname which can be resolved by DNS or a dot separated number.

EXAMPLES 08:00:20:00:61:CA pal

FILES /etc/ethers

expire.ctl

NAME

expire.ctl - control file for Usenet article expiration

DESCRIPTION

The file <pathetc in inn.conf>/expire.ctl is the default control file for the expire(8) or expireover(8) program, which read it at start-up. It serves two purposes: it defines how long history entries for expired or rejected articles are retained, and it determines how long articles not stored in a self-expiring storage method are retained. If all of the storage methods used by the server are self-expiring (such as CNFS), only the ``/remember/`` setting described below is necessary or used.

Blank lines and lines beginning with a number sign (``#``) are ignored. All other lines should be in one of two formats.

The first format specifies how long to keep history entries for articles that aren`t present in the news spool. These are articles which have either already expired out of spool or which the server rejected (and ``remembertrash`` was set to true in inn.conf(5)). There should only be one line in this format, which looks like:

: /remember/:days

where days is a floating-point number that specifies the minimum number of days a history record of a given message ID is retained, regardless of whether the article has expired. (History entries are always retained at least until an article fully expires.)

The reason to retain a record of an old articles is to handle the case where a peer offers old articles that were previously accepted and then expired. Without a setting like this, the server would accept the article again and readers would see duplicate articles. Articles older than a certain number of days won`t be accepted by the server at all (see the ``-c`` flag of innd(8)), and this setting should probably match that time period (14 days by default) to ensure the server never accepts duplicates.

This setting does not affect article expirations.

Most of the lines in this file will be in the second format, either four or five colon-separated fields as follows:

: classnum:keep:default:purge

: pattern:modflag:keep:default:purge

The former is used for class based expiry which means ``groupbaseexpiry`` in inn.conf(5) is ``false``, and the latter is used for group based expiry which means ``groupbaseexpiry`` in inn.conf is ``true``. Both formats can not coexist each other.

Where classnum field used for class based expiry is the number that you specified in storage.conf(5).

The pattern field used for group based expiry is a list of wildmat(3)-style patterns, separated by commas. This field specifies the newsgroups to which the line is applied. Note that the file is interpreted in order and the last line that matches will be used, so general patterns (like a single asterisk to set the defaults) should appear at the beginning of the file, before more specific settings.

The modflag field used for group based expiry can be used to further limit newsgroups to which the line applies, and should be chosen from the following set:

: M Only moderated groups U Only unmoderated groups A All groups X Removes the article from all groups that it appears in

(The X flag is special; normally articles are not completely deleted until they expire out of every group they were posted to, but if an article is expired by a line with an X, it is deleted out of all newsgroups it was posted to immediately.)

The rest of three fields are used to determine how long an article should be kept. Each field should be either a number of days (fractions like ``8.5`` are allowed) or the word ``never.`` The most common use is to specify the default value for how long an article should be kept. The first and third fields --- keep and purge --- specify the boundaries within which an Expires header will be honored. They are ignored if an article has no Expires header. (In other words, if an article does not have an Expires header, only default field is used and the Date header is be honored to expire. But if an article has an Expires header, default is not used, and articles are expired no faster than the time set with keep and kept no longer than the time specified with purge regardless of Expires headers). One should think of the fields as ``lower-bound default upper-bound.`` Since most articles do not have an Expires header, the second field tends to be the most important and most commonly applied one.

The keep field specifies how many days an article should be kept before it will be removed. No article in the matching newsgroups or class will be removed if it has been received for less than keep days, regardless of Expires header. If this field is the word ``never,`` no article in the matching newsgroups or class will ever be expired.

The default field specifies how long to keep an article if no Expires header is present. If this field is the word ``never`` then articles without explicit expiration dates will never be expired.

The purge field specifies the upper bound on how long an article can be kept. No article will be kept longer then the number of days specified by this field. All articles will be removed after then have been kept for purge days. If purge is the word ``never`` then the article will never be deleted.

If the line for classnum is not defined, keep, default and purge are assumed to be all ``0``. (See below for default definition.)

It is often useful to honor the Expires header in articles, especially those in moderated groups. To do this, set keep to zero, default to whatever value you wish, and purge to never (or alternately set purge to some large number, like 365 days for a maximum article life of a year). To ignore any Expires header, set all three fields to the same value.

For group based expiry, there must be exactly one line with a pattern of ``*`` and a modflags of ``A`` --- this matches all groups and is used to set the expiration default. And for class base expiry, there can be exactly one line with a class of ``255`` --- this matches all class and can be used to set the expiration default. In either case, it should be the first expiration line.

EXAMPLES

For class based expiry;

## How long to keep expired history /remember/:5 ## class 0 stay for two weeks 0:14:14:14

For group based expiry;

## How long to keep expired history /remember/:5 ## Most things stay for two weeks *:A:14:14:14 ## Believe expiration dates in moderated groups, ## up to six weeks *:M:1:30:42 ## Keep local stuff for a long time foo.*:A:30:30:30

HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is revision 1.15.2.1, dated 2000/08/17.

faillog

NAME

faillog - Login failure logging file

DESCRIPTION

faillog maintains a count of login failures and the limits for each account. The file is fixed length record, indexed by numerical UID. Each record contains the count of login failures since the last successful login; the maximum number of failures before the account is disabled; the line the last login failure occured on; and the date the last login failure occured.

The structure of the file is

        struct  faillog {

                short   fail_cnt;
                short   fail_max;
                char    fail_line[12];
                time_t  fail_time;
        };

FILES

/var/log/faillog - login failure log

AUTHOR

Julianne Frances Haugh (jockgrrl@ix.netcom.com)

faxqueue

NAME

faxqueue - sendfax fax spool queue control files

SYNOPSIS

/var/spool/fax/outgoing/F*/JOB

DESCRIPTION

The JOB files in the subdirectories of the outgoing fax spool directory, /var/spool/fax/outgoing build up a queue of faxes to be sent by faxrunq(1). They are created by faxspool(1), can be viewed with faxq(1), and be deleted by faxrm(1).

FORMAT

The format of the JOB file is as follows:

Each line consists of a leading keyword and associated data (rest of the line). Some are required, some others are optional. The currently implemented keywords are:

phone <number>: The telephone number to send the fax to. Required.
user <user>: The originating user name (on the local machine). If no "mail" field is present, this user will get the status mail about the fax. Required.
mail <email>: If this field is present, faxrunq(1) will send its status mail to the address given here. If not, faxrunq(1) will use the "user" field. Optional.
input <file(s)>: The file names passed to faxspool(1). Optional, used only by faxq(1).
pages <file(s)>: The file names, relative to the directory where the JOB file is found, that are to be sent with sendfax(8). The files have to exist, and be readable by the user that runs faxrunq(1). Required, except if "poll" is used, then it`s optional.
priority <0-9>: This can be used to set the priority for this job in the fax queue (higher priority jobs get sent before all lower-pri jobs). So far, only faxrunqd uses this field, faxrunq does NOT. 9 is the highest, 0 the lowest priority. 5 is the default.
Status <message>: Automatically appended by faxrunq(1) after each run, tells the reader about successful and unsuccessful tries to send this job. If more than five "FATAL" errors are listed, the fax job is removed from the queue.
verbose_to <blurb>: A plain-text description of the receiver of the fax. Is returned, if present, in the mail messages "your fax to <blurb>". Optional.
time <hhmm>: If present, faxrunq won`t send this job before the given time. The format must be exactly "hhmm", in 24-hr-format, otherwise faxrunq won`t understand it. Optional.
poll: Flag token. If present, faxrunq will try to poll the given phone number for documents (see "sendfax -p").
normal_res: Flag token. If present, faxrunq will transmit all pages using normal resolution (see "sendfax -n").
acct_handle <arbitrary string>: This is a pure comment field, but sendfax(8) will log it into its transaction log file. So this can be used as a customer handle, a job number, whatever you need to get the phone bills charged to the customer (the programs won`t look at it, just pass it through). Optional.
subject <arbitrary string>: This is also a pure comment field, used only for informational purposes. faxrunq will return it in the sucess/failure mail. If you use faxspool -s <subj>, it will put this string on the cover page and in the JOB file.

PERMISSIONS

Starting with mgetty 1.1.29, the fax spool directory /var/spool/fax/outgoing is no longer world-writeable. It should be owned by the user `fax` and be mode 755. The faxrunq(1) and faxrunqd(1) programs should also be run under that user ID if possible.

If the fax spool directory is world- or group-writeable, there are a number of denial of service or file overwrite / file access attacks possible that it`s very hard to guard against. So don`t do this!

If the fax spool directory has the proper permissions, there are currently no known attacks against faxrunq/faxrunqd, even if they run as "root", but it`s always more safe to run as untrusted user.

PROCESSING

While a given JOB file is processed by faxrunq(1), it`s locked against sending it multiple times by temporarily renaming it to JOB.locked, thus it may happen that a faxq(1) command doesn`t show this job. ( faxrunqd(8) is a bit smarter and does the locking by creating a hard link).

When a job is successfully sent, it`s not deleted but the JOB file is renamed to JOB.done. Because of this, you can still see old jobs with "faxq -o". You should regularly clean up the outgoing fax directory, removing old faxes. If you don`t want this behaviour, edit the faxrunq(1) config file and enable the option delete-sent-jobs yes

When a job cannot be sent after several tries (excluding normal difficulties like the called number being busy or the modem being in use), the JOB file is renamed to JOB.suspended. To re-queue this job, call faxq -r -- this renames the JOB file back.

fixheadtails.eclass

NAME

fixheadtails - functions for replacing obsolete head/tail invocations with newer POSIX compliant ones.

DESCRIPTION

The fixheadtails eclass contains functions for parsing file(s) and replacing obsolete head/tail invocations in the form similar to:

head -# <file>
with the newer POSIX compliant form of:
head -n# <file>

FUNCTIONS

NOTE: these functions are usually used in the src_unpack function.

ht_fix_file <file1> [file2] [file3] [...]: Fixes head/tail invocations in specific files.
ht_fix_all: Scans the current directory (recursively), calling ht_fix_file for each file that contains an obsolete head/tail invocation.

REPORTING BUGS

Please report bugs via http://bugs.gentoo.org/

FILES

/usr/portage/eclass/fixheadtails.eclass

AUTHORS

Aaron Walker <ka0ttic@gentoo.org>

CVS HEADER

$Header: /var/cvsroot/gentoo-src/portage/man/fixheadtails.eclass.5,v 1.3 2004/09/17 00:17:10 vapier Exp $

fmtutil.cnf

NAME

fmtutil.cnf - configuration file for fmtutil

DESCRIPTION

The fmtutil.cnf file contains the configuration information for fmtutil(8). Each line contains the name of the format (e.g., ``tex``, ``latex``, ``omega``), the name of the engine that uses that format (e.g., ``tex``, ``etex``, ``omega``), the pattern file (e.g., language.dat, language.def), and any arguments (name of an .ini file).

Fields are separated by whitespace. A ``-`` can be used to indicate an empty field (only used in practice for the pattern-file field for the tex and amstex formats, which cannot be customized in this way.). Line can be commented out with ``#``.

NOTES

The tex(1) and amstex(1) formats load hyphen.tex. No customization is available for these formats.

You can, however, build customized formats on top of plain tex(1) or amstex(1) by using bplain.tex instead of plain.tex (see, for example, the bplain.ini file for the bplain format).

etex(1) loads language.def, not language.dat.

Symbolic links to the correct engines (e.g., bplain -> tex) are generated by the texlinks(8) script. Remember to run texlinks(8) if you run fmtutil(8) yourself, rather than using the FORMATS option in texconfig(8).

FILES

fmtutil.cnf: default configuration file
language.dat: hyphenation pattern file
language.def: hyphenation pattern file

BUGS

None known, but report any bugs found to <tetex@dbs.uni-hannover.de> (mailing list).

AUTHOR

This manual page was written by C.M. Connelly <c@eskimo.com>, for the Debian GNU/Linux system. It may be used by other distributions without contacting the author. Any mistakes or omissions in the manual page are my fault; inquiries about or corrections to this manual page should be directed to me (and not to the primary author).

fonts-conf

NAME

fonts.conf - Font configuration files

SYNOPSIS

/etc/fonts/fonts.conf /etc/fonts/fonts.dtd ~/.fonts.conf

DESCRIPTION

Fontconfig is a library designed to provide system-wide font configuration, customization and application access.

FUNCTIONAL OVERVIEW

Fontconfig contains two essential modules, the configuration module which builds an internal configuration from XML files and the matching module which accepts font patterns and returns the nearest matching font.

FONT CONFIGURATION

The configuration module consists of the FcConfig datatype, libexpat and FcConfigParse which walks over an XML tree and ammends a configuration with data found within. From an external perspective, configuration of the library consists of generating a valid XML tree and feeding that to FcConfigParse. The only other mechanism provided to applications for changing the running configuration is to add fonts and directories to the list of application-provided font files.

The intent is to make font configurations relatively static, and shared by as many applications as possible. It is hoped that this will lead to more stable font selection when passing names from one application to another. XML was chosen as a configuration file format because it provides a format which is easy for external agents to edit while retaining the correct structure and syntax.

Font configuration is separate from font matching; applications needing to do their own matching can access the available fonts from the library and perform private matching. The intent is to permit applications to pick and choose appropriate functionality from the library instead of forcing them to choose between this library and a private configuration mechanism. The hope is that this will ensure that configuration of fonts for all applications can be centralized in one place. Centralizing font configuration will simplify and regularize font installation and customization.

FONT PROPERTIES

While font patterns may contain essentially any properties, there are some well known properties with associated types. Fontconfig uses some of these properties for font matching and font completion. Others are provided as a convenience for the applications rendering mechanism.

Property Type Description -------------------------------------------------------------- family String Font family name style String Font style. Overrides weight and slant slant Int Italic, oblique or roman weight Int Light, medium, demibold, bold or black size Double Point size aspect Double Stretches glyphs horizontally before hinting pixelsize Double Pixel size spacing Int Proportional, monospace or charcell foundry String Font foundry name antialias Bool Whether glyphs can be antialiased hinting Bool Whether the rasterizer should use hinting verticallayout Bool Use vertical layout autohint Bool Use autohinter instead of normal hinter globaladvance Bool Use font global advance data file String The filename holding the font index Int The index of the font within the file ftface FT_Face Use the specified FreeType face object rasterizer String Which rasterizer is in use outline Bool Whether the glyphs are outlines scalable Bool Whether glyphs can be scaled scale Double Scale factor for point->pixel conversions dpi Double Target dots per inch rgba Int unknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry minspace Bool Eliminate leading from line spacing charset CharSet Unicode chars encoded by the font lang String List of RFC-3066-style languages this font supports

FONT MATCHING

Fontconfig performs matching by measuring the distance from a provided pattern to all of the available fonts in the system. The closest matching font is selected. This ensures that a font will always be returned, but doesn`t ensure that it is anything like the requested pattern.

Font matching starts with an application constructed pattern. The desired attributes of the resulting font are collected together in a pattern. Each property of the pattern can contain one or more values; these are listed in priority order; matches earlier in the list are considered "closer" than matches later in the list.

The initial pattern is modified by applying the list of editing instructions specific to patterns found in the configuration; each consists of a match predicate and a set of editing operations. They are executed in the order they appeared in the configuration. Each match causes the associated sequence of editing operations to be applied.

After the pattern has been edited, a sequence of default substitutions are performed to canonicalize the set of available properties; this avoids the need for the lower layers to constantly provide default values for various font properties during rendering.

The canonical font pattern is finally matched against all available fonts. The distance from the pattern to the font is measured for each of several properties: foundry, charset, family, lang, spacing, pixelsize, style, slant, weight, antialias, rasterizer and outline. This list is in priority order -- results of comparing earlier elements of this list weigh more heavily than later elements.

There is one special case to this rule; family names are split into two bindings; strong and weak. Strong family names are given greater precedence in the match than lang elements while weak family names are given lower precedence than lang elements. This permits the document language to drive font selection when any document specified font is unavailable.

The pattern representing that font is augmented to include any properties found in the pattern but not found in the font itself; this permits the application to pass rendering instructions or any other data through the matching system. Finally, the list of editing instructions specific to fonts found in the configuration are applied to the pattern. This modified pattern is returned to the application.

The return value contains sufficient information to locate and rasterize the font, including the file name, pixel size and other rendering data. As none of the information involved pertains to the FreeType library, applications are free to use any rasterization engine or even to take the identified font file and access it directly.

The match/edit sequences in the configuration are performed in two passes because there are essentially two different operations necessary -- the first is to modify how fonts are selected; aliasing families and adding suitable defaults. The second is to modify how the selected fonts are rasterized. Those must apply to the selected font, not the original pattern as false matches will often occur.

FONT NAMES

Fontconfig provides a textual representation for patterns that the library can both accept and generate. The representation is in three parts, first a list of family names, second a list of point sizes and finally a list of additional properties:

<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...

Values in a list are separated with commas. The name needn`t include either families or point sizes; they can be elided. In addition, there are symbolic constants that simultaneously indicate both a name and a value. Here are some examples:

Name Meaning ---------------------------------------------------------- Times-12 12 point Times Roman Times-12:bold 12 point Times Bold Courier:italic Courier Italic in the default size Monospace:matrix=1 .1 0 1 The users preferred monospace font with artificial obliquing

LANG TAGS

Each font in the database contains a list of languages it supports. This is computed by comparing the Unicode coverage of the font with the orthography of each language. Languages are tagged using an RFC-3066 compatible naming and occur in two parts -- the ISO639 language tag followed a hyphen and then by the ISO 3166 country code. The hyphen and country code may be elided.

Fontconfig has orthographies for several languages built into the library. No provision has been made for adding new ones aside from rebuilding the library. It currently supports 122 of the 139 languages named in ISO 639-1, 141 of the languages with two-letter codes from ISO 639-2 and another 30 languages with only three-letter codes.

CONFIGURATION FILE FORMAT

Configuration files for fontconfig are stored in XML format; this format makes external configuration tools easier to write and ensures that they will generate syntactically correct configuration files. As XML files are plain text, they can also be manipulated by the expert user using a text editor.

The fontconfig document type definition resides in the external entity "fonts.dtd"; this is normally stored in the default font configuration directory (/etc/fonts). Each configuration file should contain the following structure:

<?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> <fontconfig> ... </fontconfig>

<FONTCONFIG>

This is the top level element for a font configuration and can contain dir, cache, include, match and alias elements in any order.

DIR

This element contains a directory name which will be scanned for font files to include in the set of available fonts.

CACHE

This element contains a file name for the per-user cache of font information. If it starts with `~`, it refers to a file in the users home directory. This file is used to hold information about fonts that isn`t present in the per-directory cache files. It is automatically maintained by the fontconfig library. The default for this file is ``~/.fonts.cache-version``, where version is the font configuration file version number (currently 1).

INCLUDE IGNORE_MISSING=NO

This element contains the name of an additional configuration file. When the XML datatype is traversed by FcConfigParse, the contents of the file will also be incorporated into the configuration by passing the filename to FcConfigLoadAndParse. If `ignore_missing` is set to "yes" instead of the default "no", a missing file will elicit no warning message from the library.

CONFIG

This element provides a place to consolodate additional configuration information. config can contain blank and rescan elements in any order.

BLANK

Fonts often include "broken" glyphs which appear in the encoding but are drawn as blanks on the screen. Within the blank element, place each Unicode characters which is supposed to be blank in an int element. Characters outside of this set which are drawn as blank will be elided from the set of characters supported by the font.

RESCAN

The rescan element holds an int element which indicates the default interval between automatic checks for font configuration changes. Fontconfig will validate all of the configuration files and directories and automatically rebuild the internal datastructures when this interval passes.

MATCH TARGET=PATTERN

This element holds first a (possibly empty) list of test elements and then a (possibly empty) list of edit elements. Patterns which match all of the tests are subjected to all the edits. If `target` is set to "font" instead of the default "pattern", then this element applies to the font name resulting from a match rather than a font pattern to be matched.

TEST QUAL=ANY NAME=PROPERTY COMPARE=EQ

This element contains a single value which is compared with the pattern property "property" (substitute any of the property names seen above). `compare` can be one of "eq", "not_eq", "less", "less_eq", "more", or "more_eq". `qual` may either be the default, "any", in which case the match succeeds if any value associated with the property matches the test value, or "all", in which case all of the values associated with the property must match the test value.

EDIT NAME=PROPERTY MODE=ASSIGN BINDING=WEAK

This element contains a list of expression elements (any of the value or operator elements). The expression elements are evaluated at run-time and modify the property "property". The modification depends on whether "property" was matched by one of the associated test elements, if so, the modification may affect the first matched value. Any values inserted into the property are given the indicated binding. `mode` is one of:

Mode With Match Without Match --------------------------------------------------------------------- "assign" Replace matching value Replace all values "assign_replace" Replace all values Replace all values "prepend" Insert before matching Insert at head of list "prepend_first" Insert at head of list Insert at head of list "append" Append after matching Append at end of list "append_last" Append at end of list Append at end of list

INT, DOUBLE, STRING, BOOL

These elements hold a single value of the indicated type. bool elements hold either true or false. An important limitation exists in the parsing of floating point numbers -- fontconfig requires that the mantissa start with a digit, not a decimal point, so insert a leading zero for purely fractional values (e.g. use 0.5 instead of .5 and -0.5 instead of -.5).

MATRIX

This element holds the four double elements of an affine transformation.

NAME

Holds a property name. Evaluates to the first value from the property of the font, not the pattern.

CONST

Holds the name of a constant; these are always integers and serve as symbolic names for common font values:

Constant Property Value ------------------------------------- light weight 0 medium weight 100 demibold weight 180 bold weight 200 black weight 210 roman slant 0 italic slant 100 oblique slant 110 proportional spacing 0 mono spacing 100 charcell spacing 110 unknown rgba 0 rgb rgba 1 bgr rgba 2 vrgb rgba 3 vbgr rgba 4 none rgba 5

OR, AND, PLUS, MINUS, TIMES, DIVIDE

These elements perform the specified operation on a list of expression elements. or and and are boolean, not bitwise.

EQ, NOT_EQ, LESS, LESS_EQ, MORE, MORE_EQ

These elements compare two values, producing a boolean result.

NOT

Inverts the boolean sense of its one expression element

IF

This element takes three expression elements; if the value of the first is true, it produces the value of the second, otherwise it produces the value of the third.

ALIAS

Alias elements provide a shorthand notation for the set of common match operations needed to substitute one font family for another. They contain a family element followed by optional prefer, accept and default elements. Fonts matching the family element are edited to prepend the list of prefered families before the matching family, append the acceptable familys after the matching family and append the default families to the end of the family list.

FAMILY

Holds a single font family name

PREFER, ACCEPT, DEFAULT

These hold a list of family elements to be used by the alias element. /article

EXAMPLE CONFIGURATION FILE

SYSTEM CONFIGURATION FILE

This is an example of a system-wide configuration file

<?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "fonts.dtd">  <fontconfig>  <dir>/usr/X11R6/lib/X11/fonts/truetype</dir> <dir>/usr/X11R6/lib/X11/fonts/Type1</dir>  <match target="pattern"> <test qual="any" name="family"><string>mono</string></test> <edit name="family" mode="assign"><string>monospace</string></edit> </match>  <match target="pattern"> <test qual="all" name="family" mode="not_eq">sans</test> <test qual="all" name="family" mode="not_eq">serif</test> <test qual="all" name="family" mode="not_eq">monospace</test> <edit name="family" mode="append_last"><string>sans</string></edit> </match>  <include ignore_missing="yes">~/.fonts.conf</include>  <alias> <family>Times</family> <prefer><family>Times New Roman</family></prefer> <default><family>serif</family></default> </alias> <alias> <family>Helvetica</family> <prefer><family>Verdana</family></prefer> <default><family>sans</family></default> </alias> <alias> <family>Courier</family> <prefer><family>Courier New</family></prefer> <default><family>monospace</family></default> </alias>  <alias> <family>serif</family> <prefer><family>Times New Roman</family></prefer> </alias> <alias> <family>sans</family> <prefer><family>Verdana</family></prefer> </alias> <alias> <family>monospace</family> <prefer><family>Andale Mono</family></prefer> </alias> </fontconfig>

USER CONFIGURATION FILE

This is an example of a per-user configuration file that lives in ~/.fonts.conf

<?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "fonts.dtd">  <fontconfig>  <dir>~/misc/fonts</dir>  <match target="font"> <edit name="rgba" mode="assign"><const>rgb</const></edit> </match> </fontconfig>

FILES

fonts.conf contains configuration information for the fontconfig library consisting of directories to look at for font information as well as instructions on editing program specified font patterns before attempting to match the available fonts. It is in xml format.

fonts.dtd is a DTD that describes the format of the configuration files.

~/.fonts.conf is the conventional location for per-user font configuration, although the actual location is specified in the global fonts.conf file.

~/.fonts.cache-* is the conventional repository of font information that isn`t found in the per-directory caches. This file is automatically maintained by fontconfig.

VERSION

Fontconfig version 2.2.3

fstab

NAME

fstab - static information about the filesystems

SYNOPSIS

#include <fstab.h>

DESCRIPTION

The file fstab contains descriptive information about the various file systems. fstab is only read by programs, and not written; it is the duty of the system administrator to properly create and maintain this file. Each filesystem is described on a separate line; fields on each line are separated by tabs or spaces. Lines starting with `#` are comments. The order of records in fstab is important because fsck(8), mount(8), and umount(8) sequentially iterate through fstab doing their thing.

The first field, (fs_spec), describes the block special device or remote filesystem to be mounted.

For ordinary mounts it will hold (a link to) a block special device node (as created by mknod(8)) for the device to be mounted, like `/dev/cdrom` or `/dev/sdb7`. For NFS mounts one will have <host>:<dir>, e.g., `knuth.aeb.nl:/`. For procfs, use `proc`.

Instead of giving the device explicitly, one may indicate the (ext2 or xfs) filesystem that is to be mounted by its UUID or volume label (cf. e2label(8) or xfs_admin(8)), writing LABEL=<label> or UUID=<uuid>, e.g., `LABEL=Boot` or `UUID=3e6be9de-8139-11d1-9106-a43f08d823a6`. This will make the system more robust: adding or removing a SCSI disk changes the disk device name but not the filesystem volume label.

The second field, (fs_file), describes the mount point for the filesystem. For swap partitions, this field should be specified as `none`. If the name of the mount point contains spaces these can be escaped as `40`.

The third field, (fs_vfstype), describes the type of the filesystem. Linux supports lots of filesystem types, such as adfs, affs, autofs, coda, coherent, cramfs, devpts, efs, ext2, ext3, hfs, hpfs, iso9660, jfs, minix, msdos, ncpfs, nfs, ntfs, proc, qnx4, reiserfs, romfs, smbfs, sysv, tmpfs, udf, ufs, umsdos, vfat, xenix, xfs, and possibly others. For more details, see mount(8). For the filesystems currently supported by the running kernel, see /proc/filesystems. An entry swap denotes a file or partition to be used for swapping, cf. swapon(8). An entry ignore causes the line to be ignored. This is useful to show disk partitions which are currently unused.

The fourth field, (fs_mntops), describes the mount options associated with the filesystem.

It is formatted as a comma separated list of options. It contains at least the type of mount plus any additional options appropriate to the filesystem type. For documentation on the available options for non-nfs file systems, see mount(8). For documentation on all nfs-specific options have a look at nfs(5). Common for all types of file system are the options ``noauto`` (do not mount when "mount -a" is given, e.g., at boot time), ``user`` (allow a user to mount), ``owner`` (allow device owner to mount), and ``pamconsole`` (allow a user at the console to mount), and ``_netdev`` (device requires network to be available). The ``owner``, ``pamconsole`` and ``_netdev`` options are Linux-specific. For more details, see mount(8).

The fifth field, (fs_freq), is used for these filesystems by the dump(8) command to determine which filesystems need to be dumped. If the fifth field is not present, a value of zero is returned and dump will assume that the filesystem does not need to be dumped.

The sixth field, (fs_passno), is used by the fsck(8) program to determine the order in which filesystem checks are done at reboot time. The root filesystem should be specified with a fs_passno of 1, and other filesystems should have a fs_passno of 2. Filesystems within a drive will be checked sequentially, but filesystems on different drives will be checked at the same time to utilize parallelism available in the hardware. If the sixth field is not present or zero, a value of zero is returned and fsck will assume that the filesystem does not need to be checked.

The proper way to read records from fstab is to use the routines getmntent(3).

FILES

/etc/fstab

HISTORY

The ancestor of this fstab file format appeared in 4.0BSD.

games.eclass

NAME

games - standardize the install of all games

DESCRIPTION

The games eclass is used to centrally control how all games will be emerged onto systems. Here we basically control the filesystem locations and the ownership of all files. If you want to change an aspect of how your games are installed, then just edit the games eclass ! :)

VARIABLES

GAMES_PREFIX = /usr/games: The prefix that the game will be installed under.
GAMES_PREFIX_OPT = /opt: The prefix that the game will be installed under if it is a binary distribution.
GAMES_DATADIR = /usr/share/games: The prefix for installing shared data files.
GAMES_DATADIR_BASE = /usr/share: Same as above, but some games auto append `/games/` to the datadir path.
GAMES_SYSCONFDIR = /etc/games: The location where games will save their configuration files.
GAMES_STATEDIR = /var/games: The location where games will save their state in behind runs. This includes things like highscore files. If a game creates more than one file, have it save all files inside ${GAMES_STATEDIR}/${PN}. Otherwise, just create the single file in ${GAMES_STATEDIR}/. Again, try to use a package specific name for the file if you are creating it directly in the statedir.
GAMES_LIBDIR = /usr/games/lib: The location where games will store their libraries.
GAMES_BINDIR = /usr/games/bin: The location where the games will store/link their executables. Putting game binaries here helps to cut down on the $PATH bloat.
GAMES_ENVD = 90games: The filename that the env.d entry will use.
GAMES_USER = games: The user that will own all game related files.
GAMES_GROUP = games: The group that will own all game related files.

FUNCTIONS: general

prepgamesdirs [directories]: This will change ownership on all files/directories found inside of the GAMES_* variables and any extra directories specified as parameters. It will change the permissions on all directories to 750 (u+rwx,g+rx-w,u-rwx) and change the permissions of all files with a mask of g+r,o-rwx.
*NOTE: This should *always* be the last thing called in the src_install function. If portage allowed for hookable calls then this would be hooked to the end of src_install, but until that happens, make sure to call!
games_pkg_setup: This will automagically add GAMES_USER and GAMES_GROUP to your system. If you define pkg_setup in your ebuild, then make sure to call this function at the end of the function.
games_pkg_postinst: This will automagically generate the GAMES_ENVD file and display a little message about being in the GAMES_GROUP in order to play a game. If you define pkg_postinst in your ebuild, then make sure to call this function at the end of the function.

FUNCTIONS: compile

egamesconf: The same as econf except this passes all the game related variables (see above). For more info on econf see ebuild(5).

FUNCTIONS: install

egamesinstall: The same as einstall except this passes all the game related variables (see above). For more info on einstall see ebuild(5).
dogamesbin dogamessbin: The same as dobin and dosbin respectively except these will install binaries into GAMES_PREFIX. For more info see ebuild(5).
dogameslib dogameslib.a dogameslib.so: The same as dolib, dolib.a, and dolib.so respectively except these will install binaries into GAMES_PREFIX. For more info see ebuild(5).
newgamesbin newgamessbin: The same as newbin and newsbin respectively except these will install binaries into GAMES_PREFIX. For more info see ebuild(5).
gamesowners <files/directories>: gamesowners will change the user and group ownership to GAMES_USER and GAMES_GROUP respectively.
gamesperms <files/directories>: gamesperms will change the permissions with a mask of u+rw,g+r-w,o-rwx.
games_make_wrapper <wrapper> <bin> <chdir>: Create a small wrapper script. Useful when dealing with packages that need to change directory to the base of their data tree before running. This will create a wrapper script called wrapper that will chdir to chdir before executing bin. The wrapper will be placed in GAMES_BINDIR.

REPORTING BUGS

Please report bugs via http://bugs.gentoo.org/

FILES

/usr/portage/eclass/games.eclass

AUTHORS

Mike Frysinger <vapier@gentoo.org>

CVS HEADER

$Header: /var/cvsroot/gentoo-src/portage/man/games.eclass.5,v 1.7 2004/09/17 00:17:10 vapier Exp $

getconfig.5x.php

NAME

getconfig - meta configuration files for getconfig(1)

SYNOPSIS

*.cfg

DESCRIPTION

getconfig is a programatic interface that is used by the Xorg server to get configuration information about video hardware when operating without an xorg.conf file.

This implementation of getconfig is written in perl. It processes rules from meta-configuration files. All meta-configuration files have a .cfg suffix.

Lines starting with a pound-sign (#) are comments, and are ignored. Blank lines that consist only of white space are also treated as comments and ignored.

The first non-comment line must be a signature string followed by the file format version number. The signature string is

: "Xorg getconfig rules file. Version: "

The currently defined version is "1.0". Files that do not have the correct signature string are ignored.

The remaining non-comment lines define rules. The start of a new rule is indicated by a line with no leading white space. Subsequent lines making up a rule must be indented with white space. Logical lines within a rule may be split over multiple physical lines by using the usual continuation convention (`` at the end of the line). The first logical line of each rule is a perl expression. It may be any valid perl expression whose evaluated (with `eval`) result may be used as the argument to a perl `if` statement. The second logical line should be the name of the Xorg video driver to use when the rule is true, and subsequent logical lines of each rule, if present, are additional configuration output for the video device`s xorg.conf Device section. The driver name and additional lines of configuration information are written to standard output when the rule is chosen as the successful rule.

Pseudo rules consisting of perl expressions may be present in the file for the purpose of defining custom perl variables or setting the weight to use for the following rules. Pseudo rules are rules that consist of a single logical line only, and the are never candidates themselves for the successful rule.

Several perl variables are pre-defined, and may be used within rules. They include:

: $vendor PCI vendor ID $device PCI device ID $revision PCI revision ID $subsys PCI subsystem ID $subsysVendor PCI subsystem vendor ID $class PCI class $XorgVersion Xorg version, as a `v` string $XorgVersionNumeric Xorg numeric version $XorgVersionMajor Xorg major version $XorgVersionMinor Xorg minor version $XorgVersionPatch Xorg patch version $XorgVersionSnap Xorg snap version $weight current rule weight

The $weight variable deterines the weight of the rules as they are processed. The weight for subsequent rules may be set with a pseudo rule that sets or changes the value of $weight. The default weight, and the weight used for built-in rules is 500. The meta-configuration files are processed in an unpredictable order. The weighting of the rules is used to determine their relative priority

After processing all of the rules, both built-in and those read from the meta-configration files, the getconfig program chooses as the successful rule the last and highest weighted rule that evaluates to true.

FILES

.cfg files located in the search path. The search path typically specified by the Xorg server is:

: /etc/X11 /usr/X11R6/etc/X11 <modulepath> /usr/X11R6/lib/X11/getconfig

where <modulepath> is the Xorg server`s module search path.

/usr/X11R6/lib/X11/getconfig/xorg.cfg: Default rules file that gets installed. This file doesn`t contain any rules by default.
/usr/X11R6/lib/X11/getconfig/cfg.sample: A sample rules file that gives some examples of what types of rules can appear in rules files.

AUTHORS

The Xorg automatic configuration support and the getconfig interface was written by David H. Dawes, with the support of X-Oz Technologies for XFree86.

gimprc-1.2

NAME

gimprc - gimp configuration file

DESCRIPTION

The gimprc file is a configuation file read by the gimp when it starts up. There are two of these: one system-wide one stored in /etc/gimp/1.2/gimprc and a per-user $HOME/.gimp-1.2/gimprc which may override system settings.

Comments are introduced by a hash sign (#), and continue until the end of the line. Blank lines are ignored.

The gimprc file associates values with properties. These properties may be set by lisp-like assignments of the form:

: (property-name value)
where:
property-name: is one of the property names described below.
value: is the value the property is to be set to.

Either spaces or tabs may be used to separate the name from the value.

The values have an associated type, described below:

STRING: A sequence of characters surrounded by double-quotes ("). A backslash () may be used to escape either double-quote or itself to generate a literal double-quote or a literal backslash.
PATH: Same as STRING, but path-expansion (see below) is also performed.
DOUBLE: An optional minus sign (-) followed by zero or more decimal digits, and optionally a decimal-point (.) followed by zero or more decimal digits.
FLOAT: Same as DOUBLE.
INT: Same as DOUBLE, except the value is rounded to the next lowest integer.
BOOLEAN: One of true, on, yes, false, off, or no. Alternatively, the empty string is interpreted to mean true.
POSITION: Same as two INTs separated by whitespace.
MEMSIZE: An INT followed by a size specifier. A size specifier is one of m, M, k, K, b, or B. The size specified may be omitted, in which case it defaults to k.
IMAGETYPE: One of rgb, grey, or gray.
COLORCUBE: Four whitespace separated INTs, giving the number of shades of red, green, blue and grey (respectively) in the color cube.
PREVIEWSIZE: One of none, tiny, small, medium, large or huge, or an INT. tiny is 24x24, small is 32x32, medium is 48x48, large is 64x64 and huge is 128x128.
UNIT: One of inches, millimeters, picas, or points or the identifier of one of the units you have defined in your user units database.

PROPERTIES

Valid properties and their types:

temp-path PATH

Set the temporary storage directory. Files will appear here during the course of running the gimp. Most files will disappear when the gimp exits, but some files are likely to remain, such as working palette files, so it is best if this directory not be one that is shared by other users or is cleared on machine reboot such as /tmp.

swap-path PATH

Set the swap file location. The gimp uses a tile based memory allocation scheme. The swap file is used to quickly and easily swap tiles out to disk and back in. Be aware that the swap file can easily get very large if the gimp is used with large images. Also, things can get horribly slow if the swap file is created on a directory that is mounted over NFS. For these reasons, it may be desirable to put your swap file in "/tmp".

brush-path PATH

Set the brush search path. This is a colon-separated list of directories to be searched for brushes.

pattern-path PATH

Set the pattern search path. This is a colon-separated list of directories to be searched for patterns.

plug-in-path PATH

Set the plug-in search path. This is a colon-separated list of directories which will be scanned at startup to register new plugins.

palette-path PATH

Set the palette search path. This is a colon-separated list of directories to be searched for palettes.

gradient-path PATH

Set the gradient search path. This is a colon-separated list of directories to be searched for gradients.

module-path PATH

Set the module search path. This is a colon-separated list of directories which will be scanned at startup for modules to be loaded.

default-brush STRING

Specify a default brush. This doesn`t actually do anything any more, since the default brush is set as part of the saved device status.

default-pattern STRING

Specify a default pattern. The pattern is searched for in the specified pattern path.

default-palette STRING

Specify a default palette. The palette is searched for in the specified palette path.

default-gradient STRING

Specify a default gradient. The gradient is searched for in the specified gradient path.

gamma-correction DOUBLE

Set the gamma correction value for the display. 1.0 corresponds to no gamma correction. For most displays, gamma correction should be set to between 2.0 and 2.6 Run the utility "gamma_correct" to determine appropriate values for your display. XXX is this valid info? One important item to keep in mind: Many images that you might get from outside sources will in all likelihood already be gamma-corrected. In these cases, the image will look washed-out if the gimp has gamma-correction turned on. If you are going to work with images of this sort, turn gamma correction off by setting the value to 1.0.

color-cube COLORCUBE

Set the displays color cube. No longer used in gimp-1.2.x since the introduction of GdkRgb.

install-colormap BOOLEAN

Install a private colormap by default - not actually used anymore since the introduction of GdkRgb.

tile-cache-size MEMSIZE

The tile cache is used to make sure the gimp doesn`t thrash tiles between memory and disk. Setting this value higher will cause the gimp to use less swap space, but will also cause the gimp to use more memory. Conversely, a smaller cache size causes the gimp to use more swap space and less memory. Note: the gimp will still run even if `tile-cache-size` is set to 0. The actual size can contain a suffix of `m`, `M`, size as being specified in megabytes, kilobytes and bytes respectively. If no suffix is specified the size defaults to being specified in kilobytes.

marching-ants-speed INT

Speed of marching ants in the selection outline. This value is in milliseconds (less time indicates faster marching).

last-opened-size INT

How many recently opened image filenames to keep on the File menu.

undo-levels INT

Set the number of operations kept on the undo stack.

transparency-type INT

Set the manner in which transparency is displayed in images. Transparency type can be one of 0 - Light Checks, 1 - Mid-Tone Checks, 2 - Dark Checks, 3 - White Only, 4 - Gray Only, or 5 - Black Only.

transparency-size INT

Check size can be one of 0 - Small, 1 - Medium, or 2 - Large

perfect-mouse BOOLEAN

If set to true, the X server is queried for the mouse`s current position on each motion event, rather than relying on the position hint. This means painting with large brushes should be more accurate, but it may be slower. Perversely, on some X servers turning on this option results in faster painting.

colormap-cycling BOOLEAN

Specify that marching ants for selected regions will be drawn with colormap cycling as oposed to redrawing with different stipple masks. This color cycling option works only with 8-bit displays.

default-threshold INT

Tools such as fuzzy-select and bucket fill find regions based on a seed-fill algorithm. The seed fill starts at the intially selected pixel and progresses in all directions until the difference of pixel intensity from the original is greater than a specified threshold. This value represents the default threshold.

stingy-memory-use BOOLEAN

There is always a tradeoff between memory usage and speed. In most cases, the GIMP opts for speed over memory. However, if memory is a big issue, set stingy-memory-use.

allow-resize-windows BOOLEAN

When zooming into and out of images, this option enables the automatic resizing of windows.

dont-allow-resize-windows BOOLEAN

Negated version of allow-resize-windows.

cursor-updating BOOLEAN

Context-dependent cursors are cool. They are enabled by default. However, they require overhead that you may want to do without.

no-cursor-updating BOOLEAN

Negated version of cursor-updating.

preview-size PREVIEWSIZE

Set the layer preview size.

show-rulers BOOLEAN

Set the ruler visibility. The default behavior is for rulers to be on. This can also be toggled with the View->Toggle Rulers command or shift+control+r.

dont-show-rulers BOOLEAN

Negated version of show-rulers.

show-statusbar BOOLEAN

Controlling statusbar visibility. The default behavior is to show the statusbar. This can also be toggled with the View->Toggle Statusbar command or shift+control+s.

dont-show-statusbar BOOLEAN

Negated version of show-statusbar.

auto-save BOOLEAN

Auto saving is not yet implemented! Nothing will be auto-saved, no matter how you set this.

dont-auto-save BOOLEAN

Negated version of auto-save.

interpolation-type [nearest-neighbor|linear|cubic]

Sets the level of interpolation used when scaling or transforming. By default, GIMP uses linear interpolation, which is faster, but has poorer quality than cubic interpolation.

confirm-on-close BOOLEAN

Ask for confirmation before closing an image without saving. This is the default.

dont-confirm-on-close BOOLEAN

Negated version of confirm-on-close.

save-session-info BOOLEAN

Remember the positions and sizes of the main dialogs and asks your window-manager to place them there again the next time you use the GIMP.

dont-save-session-info BOOLEAN

Negated version of save-session-info.

save-device-status BOOLEAN

Remember the current tool, pattern, color, and brush across GIMP sessions.

dont-save-device-status BOOLEAN

Negated version of save-device-status.

always-restore-session BOOLEAN

Let GIMP try to restore your last saved session.

show-tips BOOLEAN

Set to display a handy GIMP tip on startup.

dont-show-tips BOOLEAN

Negated version of show-tips.

show-tool-tips BOOLEAN

Set to display tooltips in the toolbox.

dont-show-tool-tips BOOLEAN

Negated version of show-tool-tips.

default-image-size POSITION

Set the default image size in the File/New dialog.

default-image-type IMAGETYPE

Set the default image type in the File/New dialog.

default-units UNIT

Set the default units for new images and for the File/New dialog. This units will be used for coordinate display when not in dot-for-dot mode. The default units can be one of inches , millimeters, points or picas or the identifier of one of the units defined in your user units database. The default is inches.

default-xresolution FLOAT

Set the default horizontal resolution for new images and for the File/New dialog. This value is always in dpi (dots per inch).

default-yresolution FLOAT

Set the default vertical resolution for new images and for the File/New dialog. This value is always in dpi (dots per inch).

default-resolution-units UNIT

Set the units for the display of the default resolution in the File/New dialog. The default resolution units can be one of inches, millimeters, points or picas or the identifier of one of the units defined in your user unit database. The default is inches.

monitor-xresolution FLOAT

Set the monitor`s horizontal resolution, in dots per inch. If set to 0, forces the X server to be queried for both horizontal and vertical resolution information.

monitor-yresolution FLOAT

Set the monitor`s vertical resolution, in dots per inch. If set to 0, forces the X server to be queried for both horizontal and vertical resolution information.

num-processors INT

On multiprocessor machines, if GIMP has been compiled with --enable-mp this sets how many processors GIMP should use simultaneously.

image-title-format STRING

Set the text to appear in image window titles. Certain % character sequences are recognised and expanded as follows:

%% literal percent sign
%f bare filename, or "Untitled"
%F full path to file, or "Untitled"
%p PDB image id
%i view instance number
%t image type (RGB, indexed, greyscale)
%z zoom factor as a percentage
%s source scale factor
%d destination scale factor
%Dx expands to x if the image is dirty, the empty string otherwise. The x can be any character, eg %D*.

The default format string is "%f-%p.%i (%t)".

PATH EXPANSION

Strings of type PATH are expanded in a manner similar to bash(1). Specifically: tilde (~) is expanded to the user`s home directory, and ${variable} is expanded to the current value of the variable. Note that the bash feature of being able to refer to other user`s home directories by writing ~userid/ is not valid in this file.

The only variable initially defined is gimp_dir , which is set to either the interned value .gimp-1.2 or the environment variable GIMP_DIRECTORY. If the path in GIMP_DIRECTORY is relative, it is considered relative to your home directory. The same variable expansion syntax can be used to refer to environment variables. New variables may be defined so long as their name does not shadow one of the property names given in the previous section. Variables are set using the following syntax:

: (variable-name PATH)

Note that the right hand side of this assignment is itself path expanded before setting the value of the variable.

Typically, the system-wide gimprc file will set a few convenience variables:

prefix: The installation prefix for this build, /usr.
exec_prefix: The path to architecture-specific executables, ${prefix}.
gimp_data_dir: Path to sharable data, /usr/share/gimp/1.2.
gimp_plugin_dir: Base for paths to architecture-specific plugins and modules, ${exec_prefix}/lib/gimp/1.2.

FILES

/etc/gimp/1.2/gimprc: System-wide configuration file
$HOME/.gimp-1.2/gimprc: Per-user configuration file

gnome-mime

NAME

gnome-mime - configuration files

DESCRIPTION

The GNOME system uses MIME types to classify content. Each MIME type on the GNOME system has a number of attributes attached to it. Some of these attributes have a special meaning to the GNOME system.

MIME type of files

There are two ways of classifying a file in the GNOME system: by matching their extension or a regular expression with their name or by its content. GNOME applications use one of those two methods depending on speed contraints and the specific setup. The MIME types available on the system can be configured at runtime by putting special files in either the GNOME MIME directory (${prefix}/share/mime-info) or the user ~/.gnome/mime-info directory.

MIME type definition files.

The routines that classify a file by its name, use the contents of all of the files with the extension .mime from the ${prefix}/share/mime-info directory and the ~/.gnome/mime-info to build the database for filename matching. The latter is supported to enable users to provide their mime types to extend the system defaults.

Application that wish to install their own MIME types only need to install a file in this directory.

The file ${prefix}/share/mime-info/gnome.mime is special, as it contains the defaults for gnome, and is read first. In addition, the file ~/.gnome/mime-info/user.mime is read last. This will guarantee that there is a way to set system defaults, and there is a way for the user to override them. There is currently no way to tell anything about the order of the other files in those directories, nor is there anyway to override system defaults yet.

The format is the following:

mime-type-name ext[,priority]: ext1 ext2 ext3 ext[,priority]: ext4 regex[,priority]: regex1 regex[,priority]: regex2

where "mime-type-name" is a valid MIME type. For example "text/plain".

For example, for a vCalendar application, this file would be installed:

------ calendar.mime ------- application/v-calendar: ext: vcf -----------------------------

MIME key information

To add keys to a MIME type, it is necessary to install a file with the extension .keys in the ${prefix}/share/mime-info directory or in the ~/.gnome/mime-info directory. The former is for system-provided mime-information and the latter is to enable the user to extend the actions as provided by the system.

The file ${prefix}/share/mime-info/gnome.keys is special, as it contains the defaults for gnome, and is read first. In addition, the file ~/.gnome/mime-info/user.keys is read last. This will guarantee that there is a way to set system defaults, and there is a way for the user to override them. There is currently no way to tell anything about the order of the other files in those directories, nor is there anyway to override system defaults yet.

The .keys files have the following format:

mime-type-match: [[LANG]]key=value

Above, the key is the key that is being defined and value is the value we bind to it. The optional [LANG] represents a language in which this definition is valid. If this part is specified, then the definition will only be valid if LANG matches the setting of the environment variable LANG. The LANG setting is used to provide keys which can be displayed to the user in a localized way.

This is an example to bind the key open to all of the mime-types matching image/* and the icon-filename key is bound to the /opt/gimp/share/xcf.png value:

image/*: open=gimp %f image/x-xcf: icon-filename=/opt/gimp/share/xcf.png

This will make the GIMP the handler for the open action. Files of type xcf would use the filename pointed in the icon-filename key.

%f gets interpolated with the file name or the list of file names that matched this mime-type.

As you can see from the example above, a .keys file does not need to provide all of the values, it can just provide or override some of the actions.

User defined bindings in .keys file will take precedence over system installed files.

Special key used by the GNOME system

The following keys are currently used in the GNOME desktop:

open

: Open the file with this command.

icon-filename

: The filename with the icon that should be used to represent files of this type.

view

: Command to view the file contents.

ascii-view

: A command that should be used to do an ascii-rendering of the file. Used as a fallback by the filemanager if a view action does not exist.

fm-open

: file-manager open. If present, the file manager will use this action instead of the value in open to perform this action (the filemanager for example will open archive files as if they were directories by using the VFS).

fm-view

: file-manager view. If present, invoking the view opertion on the file manager will use the value defined here instead of the value in "view".

fm-ascii-view

: Fallback operation for the file manager as well.

Those keys are also queried on the metadata (except in the cases where the lookup would be too expensive).

AUTHOR

This manual page has been written by Miguel de Icaza (miguel@gnu.org)

groff_font

NAME

groff_font - format of groff device and font description files

DESCRIPTION

The groff font format is roughly a superset of the ditroff font format. The font files for device name are stored in a directory devname. There are two types of file: a device description file called DESC and for each font F a font file called F. These are text files; unlike the ditroff font format, there is no associated binary format.

DESC file format

The DESC file can contain the following types of line as shown below. Later entries in the file override previous values.

charset: This line and everything following in the file are ignored. It is allowed for the sake of backwards compatibility.
family fam: The default font family is fam.
fonts n F1 F2 F3...Fn: Fonts F1...Fn will be mounted in the font positions m+1,...,m+n where m is the number of styles. This command may extend over more than one line. A font name of 0 will cause no font to be mounted on the corresponding font position.
hor n: The horizontal resolution is n machine units.
paperheight n: The physical vertical dimension of the output medium in machine units. This isn`t used by troff itself; currently, only grops uses it.
paperwidth n: The physical horizontal dimension of the output medium in machine units. This isn`t used by troff. Currently, only the grolbp output device uses it.
papersize string: Select a paper size. Valid values for string are the ISO paper types A0-A7, B0-B7, C0-C7, D0-D7, DL, and the US paper types letter, legal, tabloid, ledger, statement, executive, com10, and monarch. Case is not significant for string if it holds predefined paper types. Alternatively, string can be a file name (e.g. `/etc/papersize`); if the file can be opened, groff reads the first line and tests for the above paper sizes. Finally, string can be a custom paper size in the format length,width (no spaces before and after the comma). Both length and width must have a unit appended; valid values are `i` for inches, `c` for centimeters, `p` for points, and `P` for picas. Example: 12c,235p. An argument which starts with a digit is always treated as a custom paper format. papersize sets both the vertical and horizontal dimension of the output medium.
: More than one argument can be specified; groff scans from left to right and uses the first valid paper specification.
pass_filenames: Make troff tell the driver the source file name being processed. This is achieved by another tcommand: F filename.
postpro program: Use program as the postprocessor.
prepro program: Call program as a preprocessor.
print program: Use program as the spooler program for printing. If omitted, the -l and -L options of groff are ignored.
res n: There are n machine units per inch.
sizes s1 s2...sn 0: This means that the device has fonts at s1, s2,...sn scaled points. The list of sizes must be terminated by a 0. Each si can also be a range of sizes m-n. The list can extend over more than one line.
sizescale n: The scale factor for pointsizes. By default this has a value of 1. One scaled point is equal to one point/n. The arguments to the unitwidth and sizes commands are given in scaled points.
styles S1 S2...Sm: The first m font positions will be associated with styles S1...Sm.
tcommand: This means that the postprocessor can handle the t and u output commands.
unitwidth n: Quantities in the font files are given in machine units for fonts whose point size is n scaled points.
use_charnames_in_special: This command indicates that troff should encode named characters inside special commands.
vert n: The vertical resolution is n machine units.

The res, unitwidth, fonts, and sizes lines are compulsory. Other commands are ignored by troff but may be used by postprocessors to store arbitrary information about the device in the DESC file.

Here a list of obsolete keywords which are recognized by groff but completely ignored: spare1, spare2, biggestfont.

Font file format

A font file has two sections. The first section is a sequence of lines each containing a sequence of blank delimited words; the first word in the line is a key, and subsequent words give a value for that key.

ligatures lig1 lig2...lign [0]: Characters lig1, lig2, ..., lign are ligatures; possible ligatures are ff, fi, fl, ffi and ffl. For backwards compatibility, the list of ligatures may be terminated with a 0. The list of ligatures may not extend over more than one line.
name F: The name of the font is F.
slant n: The characters of the font have a slant of n degrees. (Positive means forward.)
spacewidth n: The normal width of a space is n.
special: The font is special; this means that when a character is requested that is not present in the current font, it will be searched for in any special fonts that are mounted.

Other commands are ignored by troff but may be used by postprocessors to store arbitrary information about the font in the font file.

The first section can contain comments which start with the # character and extend to the end of a line.

The second section contains one or two subsections. It must contain a charset subsection and it may also contain a kernpairs subsection. These subsections can appear in any order. Each subsection starts with a word on a line by itself.

The word charset starts the charset subsection. The charset line is followed by a sequence of lines. Each line gives information for one character. A line comprises a number of fields separated by blanks or tabs. The format is

: name metrics type code [entity_name] [-- comment]

name identifies the character: if name is a single character c then it corresponds to the groff input character c; if it is of the form [rs]c where c is a single character, then it corresponds to the special character [rs][c]; otherwise it corresponds to the groff input character [rs][name]. If it is exactly two characters xx it can be entered as [rs](xx. Note that single-letter special characters can`t be accessed as [rs]c; the only exception is `[rs]-` which is identical to `[rs][-]`. The name --- is special and indicates that the character is unnamed; such characters can only be used by means of the [rs]N escape sequence in troff.

Groff supports eight-bit characters; however some utilities have difficulties with eight-bit characters. For this reason, there is a convention that the name charn is equivalent to the single character whose code is n. For example, char163 would be equivalent to the character with code 163 which is the pounds sterling sign in ISO Latin-1.

The type field gives the character type:

1: means the character has a descender, for example, p;
2: means the character has an ascender, for example, b;
3: means the character has both an ascender and a descender, for example, (.

The code field gives the code which the postprocessor uses to print the character. The character can also be input to groff using this code by means of the [rs]N escape sequence. The code can be any integer. If it starts with a 0 it will be interpreted as octal; if it starts with 0x or 0X it will be intepreted as hexadecimal. Note, however, that the [rs]N escape sequence only accepts a decimal integer.

The entity_name field gives an ascii string identifying the glyph which the postprocessor uses to print the character. This field is optional and has been introduced so that the html device driver can encode its character set. For example, the character `[rs][Po]` is represented as `£` in html~4.0.

Anything on the line after the encoding field resp. after `--` will be ignored.

The metrics field has the form (in one line; it is broken here for the sake of readability):

: width[,height[,depth[,italic-correction
[,left-italic-correction[,subscript-correction]]]]]

There must not be any spaces between these subfields. Missing subfields are assumed to be 0. The subfields are all decimal integers. Since there is no associated binary format, these values are not required to fit into a variable of type char as they are in ditroff. The width subfields gives the width of the character. The height subfield gives the height of the character (upwards is positive); if a character does not extend above the baseline, it should be given a zero height, rather than a negative height. The depth subfield gives the depth of the character, that is, the distance below the lowest point below the baseline to which the character extends (downwards is positive); if a character does not extend below above the baseline, it should be given a zero depth, rather than a negative depth. The italic-correction subfield gives the amount of space that should be added after the character when it is immediately to be followed by a character from a roman font. The left-italic-correction subfield gives the amount of space that should be added before the character when it is immediately to be preceded by a character from a roman font. The subscript-correction gives the amount of space that should be added after a character before adding a subscript. This should be less than the italic correction.

A line in the charset section can also have the format

: name "

This indicates that name is just another name for the character mentioned in the preceding line.

The word kernpairs starts the kernpairs section. This contains a sequence of lines of the form:

: c1 c2 n

This means that when character c1 appears next to character c2 the space between them should be increased by n. Most entries in kernpairs section will have a negative value for n.

FILES

u+3n

: /usr/share/groff/1.18.1.1/font/devname/DESC Device description file for device name.
/usr/share/groff/1.18.1.1/font/devname/F: Font file for font F of device name.

group

NAME

group - user group file

DESCRIPTION

/etc/group is an ASCII file which defines the groups to which users belong. There is one entry per line, and each line has the format:

: group_name:passwd:GID:user_list

The field descriptions are:

group_name: the name of the group.
password: the (encrypted) group password. If this field is empty, no password is needed.
GID: the numerical group ID.
user_list: all the group member`s user names, separated by commas.

FILES

/etc/group

hesiod.conf

NAME

hesiod.conf - Configuration file for the Hesiod library

DESCRIPTION

The file hesiod.conf determines the behavior of the Hesiod library. Blank lines and lines beginning with a `#` character are ignored. All other lines should be of the form variable = value, where the value should be a single word. Possible variables and values are:

lhs: Specifies the domain prefix used for Hesiod queries. In almost all cases, you should specify ``lhs=.ns``. The default value if you do not specify an lhs value is no domain prefix, which is not compatible with most Hesiod domains.
rhs: Specifies the default Hesiod domain; this value may be overridden by the HES_DOMAIN environment variable. You must specify an rhs line for the Hesiod library to work properly.
classes: Specifies which DNS classes Hesiod should do lookups in. Possible values are IN (the preferred class) and HS (the deprecated class, still used by some sites). You may specify both classes separated by a comma to try one class first and then the other if no entry is available in the first class. The default value of the classes variable is ``IN,HS``.

BUGS

There default value for ``lhs`` should probably be more reasonable.

horde.eclass

NAME

horde - standardize the installation of horde packages

DESCRIPTION

The horde eclass provides generic functions to make the writing of horde ebuilds trivial. The horde eclass also provides transparent support for live CVS ebuilds via the cvs.eclass(5) (when ${PN} contains "-cvs").

VARIABLES

HORDE_PHP_FEATURES A whitespace-delimited list of mod_php USE flags. If set, horde_pkg_setup will check to make sure that mod_php was compiled with the specified USE flags. If not, the build will fail, notifying the user that they must rebuild mod_php with the specified USE flags.

FUNCTIONS

horde_pkg_setup: Handles the nasty details of the webapp.eclass(5) and checks HORDE_PHP_FEATURES, if set.
horde_src_unpack: In the case of a live CVS ebuild, this function calls cvs_src_unpack from the cvs eclass. Otherwise, unpack is called.
horde_src_install: Installs all files in ${S} into the webapp eclass` ${MY_HTDOCSDIR} directory. This will also installs documentation (the README and all files in in ${S}/docs/). Then the rest of the nasty details of the webapp.eclass(5) are taken care of.
horde_pkg_postinst: Displays various informational and/or warning messages.

REPORTING BUGS

Please report bugs via http://bugs.gentoo.org/

FILES

/usr/portage/eclass/horde.eclass /usr/portage/eclass/webapp.eclass /usr/portage/eclass/cvs.eclass

AUTHORS

Aaron Walker <ka0ttic@gentoo.org> Mike Frysinger <vapier@gentoo.org>

CVS HEADER

$Header: /var/cvsroot/gentoo-src/portage/man/horde.eclass.5,v 1.3 2004/09/17 00:17:10 vapier Exp $

hosts

NAME

hosts - The static table lookup for host names

SYNOPSIS

/etc/hosts

DESCRIPTION

This manual page describes the format of the /etc/hosts file. This file is a simple text file that associates IP addresses with hostnames, one line per IP address. For each host a single line should be present with the following information:

: IP_address canonical_hostname aliases

Fields of the entry are separated by any number of blanks and/or tab characters. Text from a "#" character until the end of the line is a comment, and is ignored. Host names may contain only alphanumeric characters, minus signs ("-"), and periods ("."). They must begin with an alphabetic character and end with an alphanumeric character. Aliases provide for name changes, alternate spellings, shorter hostnames, or generic hostnames (for example, localhost). The format of the host table is described in RFC 952.

The Berkeley Internet Name Domain (BIND) Server implements the Internet name server for UNIX systems. It augments or replaces the /etc/hosts file or host name lookup, and frees a host from relying on /etc/hosts being up to date and complete.

In modern systems, even though the host table has been superseded by DNS, it is still widely used for:

bootstrapping: Most systems have a small host table containing the name and address information for important hosts on the local network. This is useful when DNS is not running, for example during system bootup.
NIS: Sites that use NIS use the host table as input to the NIS host database. Even though NIS can be used with DNS, most NIS sites still use the host table with an entry for all local hosts as a backup.
isolated nodes: Very small sites that are isolated from the network use the host table instead of DNS. If the local information rarely changes, and the network is not connected to the Internet, DNS offers little advantage.

EXAMPLE

127.0.0.1 localhost 192.168.1.10 foo.mydomain.org foo 192.168.1.13 bar.mydomain.org bar 216.234.231.5 master.debian.org master 205.230.163.103 www.opensource.org

HISTORICAL NOTE

Before the advent of DNS, the host table was the only way of resolving hostnames on the fledgling Internet. Indeed, this file could be created from the official host data base maintained at the Network Information Control Center (NIC), though local changes were often required to bring it up to date regarding unofficial aliases and/or unknown hosts. The NIC no longer maintains the hosts.txt files, though looking around at the time of writing (circa 2000), there are historical hosts.txt files on the WWW. I just found three, from 92, 94, and 95.

FILES

/etc/hosts

AUTHOR

This manual page was written by Manoj Srivastava <srivasta@debian.org>, for the Debian GNU/Linux system.

hosts.equiv

NAME

/etc/hosts.equiv - list of hosts and users that are granted "trusted" r command access to your system

DESCRIPTION

The hosts.equiv file allows or denies hosts and users to use the r-commands (e.g. rlogin, rsh or rcp) without supplying a password.

The file uses the following format:

[ + | - ] [hostname] [username]

The hostname is the name of a host which is logically equivalent to the local host. Users logged into that host are allowed to access like-named user accounts on the local host without supplying a password. The hostname may be (optionally) preceded by a plus (+) sign. If the plus sign is used alone it allows any host to access your system. You can expicitly deny access to a host by preceding the hostname by a minus (-) sign. Users from that host must always supply a password. For security reasons you should always use the FQDN of the hostname and not the short hostname.

The username entry grants a specific user access to all user accounts (except root) without supplying a password. That means the user is NOT restricted to like-named accounts. The username may be (optionally) preceded by a plus (+) sign. You can also explicitly deny access to a specific user by preceding the username with a minus (-) sign. This says that the user is not trusted no matter what other entries for that host exist.

Netgroups can be specified by preceding the netgroup by an @ sign.

Be extremely careful when using the plus (+) sign. A simple typographical error could result in a standalone plus sign. A standalone plus sign is a wildcard character that means "any host"!

FILES

/etc/hosts.equiv

NOTES

Some systems will only honor the contents of this file when it has owner root and no write permission for anybody else. Some exceptionally paranoid systems even require that there be no other hard links to the file.

Modern systems use the Pluggable Authentication Modules library (PAM). With PAM a standalone plus sign is only considered a wildcard character which means "any host" when the word promiscuous is added to the auth component line in your PAM file for the particular service (e.g. rlogin).

iftab

NAME

iftab - static information about the network interfaces

DESCRIPTION

The file /etc/iftab contains descriptive information about the various network interfaces. iftab is only used by the program ifrename(8) to assign a consistent network interface name to each network interface.

/etc/iftab defines a set of mappings. Each mapping contains an interface name and a set of selectors. The selectors allow ifrename to identify each network interface on the system. If a network interface matches all descriptors of a mapping, ifrename attempt to change the name of the interface to the interface name given by the mapping.

MAPPINGS

Each mapping is described on a separate line, it starts with an interface name, and contains a set of descriptors, separated by space or tabs.

The relationship between descriptors of a mapping is a logical and. A mapping matches a network interface only is all the descriptors match. If a network interface doesn`t support a specific descriptor, it won`t match any mappings using this descriptor.

If you want to use alternate descriptors for an interface name (logical or), specify two different mappings with the same interface name (one on each line). Ifrename always use the first matching mapping starting from the end of iftab, therefore more restrictive mapping should be specified last.

INTERFACE NAME

The first part of each mapping is an interface name. If a network interface matches all descriptors of a mapping, ifrename attempt to change the name of the interface to the interface name given by the mapping.

The interface name of a mapping is either a plain interface name (such as eth2 or wlan0) or a interface name pattern containing a single wildcard (such as eth* or wlan*). In case of wildcard, the kernel replace the `*` with the lowest available integer making this interface name unique.

DESCRIPTORS

Each descriptor is composed of a descriptor name and descriptor value. Descriptors specify a static attribute of a network interface, the goal is to uniquely identify each piece of hardware.

Most users will only use the mac selector, other selectors are for more specialised setup.

mac mac address: Matches the MAC Address of the interface with the specified MAC address. The MAC address of the interface can be shown using ifconfig(8) or ip(8). The specified MAC address may contain a `*` for wilcard matching.
This is the most common selector, as most interfaces have a unique MAC address allowing to identify network interfaces without ambiguity.
arp arp type: Matches the ARP Type (also called Link Type) of the interface with the specified ARP type. The ARP Type of the interface can be shown using ifconfig(8) or ip(8).
This selector is useful when a driver create multiple network interfaces for a single network card.
driver driver name: Matches the Driver Name of the interface with the specified driver name. The Driver Name of the interface can be shown using ethtool -i(8).
businfo bus information: Matches the Bus Information of the interface with the specified bus information. The Bus Information of the interface can be shown using ethtool -i(8).
baseaddress base address: Matches the Base Address of the interface with the specified base address. The Base Address of the interface can be shown using ifconfig(8).
Because most cards use dynamic allocation of the Base Address, this selector is only useful for ISA and EISA cards.
irq irq line: Matches the IRQ Line (interrupt) of the interface with the specified IRQ line. The IRQ Line of the interface can be shown using ifconfig(8).
Because there are IRQ Lines may be shared, this selector is usually not sufficient to uniquely identify an interface.
iwproto wireless protocol: Matches the Wireless Protocol of the interface with the specified wireless protocol. The Wireless Protocol of the interface can be shown using iwconfig(8).
This selector is only supported on wireless interfaces and is not sufficient to uniquely identify an interface.

EXAMPLE

# This is a comment
eth2           mac 08:00:09:DE:82:0E

eth3           driver wavelan interrupt 15 baseaddress 0x390

eth4           driver pcnet32 businfo 0000:02:05.0

air*           mac 00:07:0E:* arp 1

AUTHOR

Jean Tourrilhes - jt@hpl.hp.com

FILES

/etc/iftab

incoming.conf

NAME

incoming.conf - names and addresses that feed us news

DESCRIPTION

The file <pathetc in inn.conf>/incoming.conf consists of three types of entries: key/value, peer and group. Comments are taken from the hash character ``#`` to the end of the line. Blank lines are ignored. All key/value entries within each type must not be duplicated.

Key/value entries are a keyword immediately followed by a colon, at least one blank and a value. For example:

: max-connections: 10

A legal key contains nor blanks, nor colon, nor ``#``. There are 3 different types of values: integers, booleans, and strings. Integers are as to be expected. A boolean value is either ``true`` or ``false`` (case is significant). A string value is any other sequence of characters. If the string needs to contain whitespace, then it must be quoted with double quotes.

Peer entries look like:

: peer <name> { # body }

The word ``peer`` is required. ``<name>``is a label for this peer. The ``<name>`` is any string valid as a key. The body of a peer entry contains some number of key/value entries.

Group entries look like:

: group <name> { # body }

The word ``group`` is required. The ``<name>`` is any string valid as a key. The body of a group entry contains any number of the three types of entries. So key/value pairs can be defined inside a group, and peers can be nested inside a group, and other groups can be nested inside a group.

Key/value entries that are defined outside of all peer and group entries are said to be at ``global scope``. Global key/value entries act as defaults for peers. When innd(8) looks for a specific value in a peer entry (for example, the maximum number of connections to allow), if the value is not defined in the peer entry, then the enclosing groups are examined for the entry (starting at the closest enclosing group). If there are no enclosing groups, or the enclosing groups don`t define the key/value, then the value at global scope is used.

A small example could be:

: # Global value applied to all peers that have # no value of their own. max-connections: 5 # A peer definition. peer uunet { hostname: usenet1.uu.net } peer vixie { hostname: gw.home.vix.com max-connections: 10 # override global value. } # A group of two peers who can open more # connections than normal group fast-sites { max-connections: 15 # Another peer. The ``max-connections`` value from the # ``fast-sites`` group scope is used. The ``hostname`` value # defaults to the peer`s name. peer data.ramona.vix.com { } peer bb.home.vix.com { hostname: bb.home.vix.com max-connections: 20 # he can really cook. } }

Given the above configuration file, the defined peers would have the following values for the ``max-connections`` key.

: uunet 5 vixie 10 data.ramona.vix.com 15 bb.home.vix.com 20

Ten keys are allowed:

hostname:: This key requires a string value. It is a list of hostnames separated by a comma. A hostname is the host`s FQDN, or the dotted quad ip-address of the peer. If this key is not present in a peer block, the hostname defaults to the label of the peer.
streaming:: This key requires a boolean value. It defines whether streaming commands are allowed from this peer. (default=true)
max-connections:: This key requires positive integer value. It defines the maximum number of connections allowed. A value of zero specifies an unlimited number of maximum connections (``unlimited`` or ``none`` can be used as synonym). (default=0)
hold-time:: This key requires positive integer value. It defines the hold time before close, if the connection is over max-connections. A value of zero specifies immediate close. (default=0)
password:: This key requires a string value. It is used if you wish to require a peer to supply a password. (default=no password)
patterns:: This key requires a string value. It is a list of newsfeeds(5) style list of newsgroups which are to be accepted from this host. (default="*")
email:: This key requires a string value. Reserved for future use. (default=empty)
comment:: This key requires a string value. Reserved for future use. (default=empty)
skip:: This key requires a boolean value. Setting this entry causes this peer to be skipped. (default=false)
noresendid:: This key requires a boolean value. It defines whether innd(8) should send ``431 RESENDID`` responses if a message is offered that is being received from another peer. This can be useful for peers that resend messages right away, as innfeed does. (default=false)

HISTORY

Written by Fabien Tassin <fta@sofaraway.org> for InterNetNews. This is revision 1.11.2.3, dated 2001/01/12.

initscript

NAME

initscript - script that executes inittab commands.

SYNOPSIS

/bin/sh /etc/initscript id runlevels action process

DESCRIPTION

When the shell script /etc/initscript is present, init will use it to execute the commands from inittab. This script can be used to set things like ulimit and umask default values for every process.

EXAMPLES

This is a sample initscript, which might be installed on your system as /etc/initscript.sample.

# # initscript Executed by init(8) for every program it # wants to spawn like this: # # /bin/sh /etc/initscript <id> <level> <action> <process> # # Set umask to safe level, and enable core dumps. umask 022 ulimit -c 2097151 PATH=/bin:/sbin:/usr/bin:/usr/sbin export PATH # Increase the hard filedescriptor limit for all processes # to 8192. The soft limit is still 1024, but any unpriviliged # process can increase it`s soft limit up to the hardlimit # with "ulimit -Sn xxx" (needs a 2.2.13 or later Linux kernel). ulimit -Hn 8192 # Execute the program. eval exec "$4"

FILES

/etc/inittab, /etc/initscript.

AUTHOR

Miquel van Smoorenburg ,<miquels@cistron.nl>

inn.conf

NAME

inn.conf - Configuration data for InterNetNews programs

DESCRIPTION

inn.conf in pathetc is the primary general configuration file for all InterNetNews programs. Settings which control the general operation of various programs, as well as the paths to all portions of the news installation, are found here. The INNCONF environment variable, if set, specifies an alternate path to inn.conf.

This file is intended to be fairly static. Any changes made to it will generally not affect any running programs until they restart. Unlike nearly every other configuration file, inn.conf cannot be reloaded dynamically using ctlinnd(8); innd(8) must be stopped and restarted for relevant changes to inn.conf to take effect ("ctlinnd xexec innd" is the fastest way to do this.)

Blank lines and lines starting with a number sign ("#") are ignored. All other lines specify parameters, and should be of the following form:

(Any amount of whitespace can be put after the colon and is optional.) Everything after the colon and optional whitespace up to the end of the line is taken as the value. Multi-word values should not be put in quotes; if they are, the quotes will be taken as part of the value, not as delimiters. <name> is case-sensitive; "server" is not the same as "Server" or "SERVER". (inn.conf parameters are generally all in lowercase.)

If <name> occurs more than once in the file, the first value is used. Some parameters specified in the file may be overridden by environment variables. Most parameters have default values if not specified in inn.conf; those defaults are noted in the description of each parameter.

For the time being, it is strongly recommended to include every parameter in inn.conf even if it is set to the default value, since some shell scripts don`t correctly handle missing keys that they care about. This is a difficult-to-fix bug in the current parser that will be fixed in future versions of INN.

Many parameters take a boolean value. For all such parameters, the value may be specified as "true", "yes", or "on" to turn it on and may be any of "false", "no", or "off" to turn it off. The case of these values is not significant.

This documentation is extremely long and organized as a reference manual rather than as a tutorial. If this is your first exposure to INN and these parameters, it would be better to start by reading other man pages and referring to this one only when an inn.conf parameter is explicitly mentioned.

PARAMETERS

General Settings

These parameters are used by a wide variety of different components of INN.

domain: This should be the domain name of the local host. It should not have a leading period, and it should not be a full host address. It is used only if the GetFQDN() routine in libinn(3) cannot get the fully-qualified domain name by using either the gethostname(3) or gethostbyname(3) calls. The check is very simple; if either routine returns a name with a period in it, then it is assumed to have the full domain name. The default value is unset.
innflags: The flags to pass to innd on startup. See innd(8) for details on the possible flags. The default value is unset.
mailcmd: The path to the program to be used for mailing reports and control messages. The default is pathbin/innmail. This should not normally need to be changed.
mta: The command to use when mailing postings to moderators and for the use of innmail(1). The message, with headers and an added To: header, will be piped into this program. The string %s, if present, will be replaced by the e-mail address of the moderator. It`s strongly recommended for this command to include %s on the command line rather than use the addresses in the To: and Cc: headers of the message, since the latter approach allows the news server to be abused as a mechanism to send mail to arbitrary addresses and will result in unexpected behavior. There is no default value for this parameter; it must be set in inn.conf or a fatal error message will be logged via syslog.
For most systems, "/usr/lib/sendmail -oi -oem %s" (adjusted for the correct path to sendmail) is a good choice.
pathhost: What to put into the Path: header to represent the local site. This is added to the Path: header of all articles that pass through the system, including locally posted articles, and is also used when processing some control messages and when naming the server in status reports. There is no default value; this parameter must be set in inn.conf or INN will not start. A good value to use is the fully-qualified hostname of the system.
server: The name of the default NNTP server. If nnrpdposthost is not set and UNIX domain sockets are not supported, nnrpd(8) tries to hand off locally-posted articles through an INET domain socket to this server. actsync(8), nntpget(8), and getlist(8) also use this value as the default server to connect to. In the latter cases, the value of the NNTPSERVER environment variable, if it exists, overrides this. The default value is unset.

Feed Configuration

These parameters govern incoming and outgoing feeds: what size of articles are accepted, what filtering and verification is performed on them, whether articles in groups not carried by the server are still stored and propagated, and other similar settings.

artcutoff: Articles older than this number of days are dropped. This setting should probably match the setting on the "/remember/" line in expire.ctl. The default value is 10.
bindaddress: Which IP address innd(8) should bind itself to. This must be in dotted-quad format (nnn.nnn.nnn.nnn). If set to "all" or not set, innd defaults to listening on all interfaces. The value of the INND_BIND_ADDRESS environment variable, if set, overrides this setting. The default value is unset.
hiscachesize: If set to a value other than 0, a hash of recently received message IDs is kept in memory to speed history lookups. The value is the amount of memory to devote to the cache in kilobytes. The cache is only used for incoming feeds and a small cache can hold quite a few message IDs, so large values aren`t necessarily useful unless you have incoming feeds that are badly delayed. A good value for a system with more than one incoming feed is 256; systems with only one incoming feed should probably leave this at 0. The default value is 0.
ignorenewsgroups: Whether newsgroup creation control messages (newgroup and rmgroup) should be fed as if they were posted to the newsgroup they are creating or deleting rather than to the newsgroups listed in the Newsgroups: header. If this parameter is set, the newsgroup affected by the control message will be extracted from the Control: or Subject: header and the article will be fed as if its Newsgroups: header contained solely that newsgroup. This is useful for routing control messages to peers when they are posted to irrelevant newsgroups that shouldn`t be matched against the peer`s desired newsgroups in newsfeeds. This is a boolean value and the default is false.
immediatecancel: When using the timecaf storage method, article cancels are normally just cached to be cancelled, not cancelled immediately. If this is set to true, they will instead by cancelled as soon as the cancel is processed. This is a boolean value and the default is false.
This setting is ignored unless the timecaf storage method is used.
linecountfuzz: If set to something other than 0, the line count of the article is checked against the Lines: header of the article (if present) and the artice is rejected if the values differ by more than this amount. A reasonable setting is 5, which is the standard maximum signature length plus one (some injection software calculates the Lines: header before adding the signature). The default value is 0, which tells INN not to check the Lines: header of incoming articles.
maxartsize: The maximum size of article (headers and body) that will be accepted by the server, in bytes. A value of 0 allows any size of article. The default value is 1000000 (approximately 1MB). See also localmaxartsize.
maxconnections: The maximum number of incoming NNTP connections innd(8) will accept. The default value is 50.
pathalias: If set, this value is prepended to the Path: header of accepted posts (before pathhost) if it doesn`t already appear in the Path: header. The main purpose of this parameter is to configure all news servers within a particular organization to add a common identity string to the Path: header. The default value is unset.
pgpverify: Whether to enable PGP verification of control messages other than cancel. This is a boolean value and the default is based on whether configure found pgp or pgpv.
port: What TCP port innd(8) should listen on. The default value is 119, the standard NNTP port.
refusecybercancels: Whether to refuse all articles whose message IDs start with "<cancel.". This message ID convention is widely followed by spam cancellers, so the vast majority of such articles will be cancels of spam. This check, if enabled, is done before the history check and the message ID is not written to the history file. This is a boolean value and the default is false.
This is a somewhat messy, inefficient, and inexact way of refusing spam cancels. A much better way is to ask all of your upstream peers to not send to you any articles with "cyberspam" in the Path: header (usually accomplished by having them mark "cyberspam" as an alias for your machine in their feed configuration). The filtering enabled by this parameter is hard-coded; general filtering of message IDs can be done via the embedded filtering support.
remembertrash: By default, innd(8) records rejected articles in history so that, if offered the same article again, it can be refused before it is sent. If you wish to disable this behavior, set this to false. This can cause a substantial increase in the amount of bandwidth consumed by incoming news if you have several peers and reject a lot of articles, so be careful with it. Even if this is set to true, INN won`t log some rejected articles to history if there`s reason to believe the article might be accepted if offered by a different peer, so there is usually no reason to set this to false (although doing so can decrease the size of the history file). This is a boolean value and the default is true.
sourceaddress: Which local IP address to bind to for outgoing NNTP sockets (used by innxmit(8) among other programs). This must be in dotted-quad format (nnn.nnn.nnn.nnn). If set to "all" or not set, the operating system will choose the source IP address for outgoing connections. The default value is unset.
usecontrolchan: Whether to handle control messages (other than cancel) in an external program rather than internally in innd(8). Enabling this is highly recommended, as INN`s internal control message handling can cause performance problems and behaves very poorly under heavy load. If you want to enable this, you also must set up a channel feed to controlchan(8) in newsfeeds(5) and ensure that the group "control.cancel" exists on your server. You may also have to do a few additional things to allow controlchan to work correctly; see controlchan(8) for the details. This is a boolean value and the default is false.
verifycancels: Set this to true to enable a simplistic check on all cancel messages, attempting to verify (by simple header comparison) that the cancel message is from the same person as the original post. This can`t be done if the cancel arrives before the article does, and is extremely easy to spoof. While this check may once have served a purpose, it`s now essentially security via obscurity, commonly avoided by abusers, and probably not useful. This is a boolean value, and the default is false.
wanttrash: Set this to true if you want to file articles posted to unknown newsgroups (newsgroups not in the active file) into the "junk" newsgroup rather than rejecting them. This is sometimes useful for a transit news server that needs to propagate articles in all newsgroups regardless if they`re carried locally. This is a boolean value and the default is false.
wipcheck: If INN is offered an article by a peer on one channel, it will return deferral responses (code 436) to all other offers of that article for this many seconds. (After this long, if the peer that offered the article still hasn`t sent it, it will be accepted from other channels.) The default value is 5 and probably doesn`t need to be changed.
wipexpire: How long, in seconds, to keep track of message IDs offered on a channel before expiring articles that still haven`t been sent. The default value is 10 and probably doesn`t need to be changed.

Article Storage

These parameters affect how articles are stored on disk.

cnfscheckfudgesize

If set to a value other than 0, the claimed size of articles in CNFS cycbuffs is checked against maxartsize plus this value, and if larger, the CNFS cycbuff is considered corrupt. This can be useful as a sanity check after a system crash, but be careful using this parameter if you have changed maxartsize recently. The default value is 0.

enableoverview

Whether to write out overview data for articles. If set to false, INN will run much faster, but reading news from the system will be impossible (the server will be for news transit only). If this option is set to true, ovmethod must also be set. This is a boolean value and the default is true.

groupbaseexpiry

Whether to enable newsgroup-based expiry. If set to false, article expiry is done based on storage class of storing method. If set to true (and overview information is available), expiry is done by newsgroup name. This effects the format of expire.ctl. This is a boolean value and the default is true.

mergetogroups

Whether to file all postings to "to.*" groups in the pseudonewsgroup "to". If this is set to true, the newsgroup "to" must exist in the active file or INN will not start. This is a boolean value and the default is false.

overcachesize

How many cache slots to reserve for open overview files. If INN is writing overview files (see enableoverview), ovmethod is set to "tradindexed", and this is set to a value other than 0, INN will keep around and open that many recently written-to overview files in case more articles come in for those newsgroups. Every overview cache slot consumes two file descriptors, so be careful not to set this value too high. You may be able to use the "limit" command to see how many open file descriptors your operating system allows. innd(8) also uses an open file descriptor for each incoming feed and outgoing channel or batch file, and if it runs out of open file descriptors it may throttle and stop accepting new news. The default value is 15 (which is probably way too low if you have a large number of file descriptors available).

This setting is ignored unless ovmethod is set to "tradindexed".

ovgrouppat

If set, restricts the overview data stored by INN to only the newsgroups matching this comma-separated list of wildmat expressions. Newsgroups not matching this setting may not be readable, and if groupbaseexpiry is set to true and the storage method for these newsgroups does not have self-expire functionality, storing overview data will fail. The default is unset.

ovmethod

Which overview storage method to use. Currently supported values are "tradindexed", "buffindexed", and "ovdb". There is no default value; this parameter must be set if enableoverview is true (the default).

buffindexed: Stores overview data and index information into buffers, which are preconfigured files defined in buffinedexed.conf. "buffindexed" never consumes additional disk space beyond that allocated to these buffers.
tradindexed: Uses two files per newsgroup, one containing the overview data and one containing the index. Fast for readers, but slow to write to.
ovdb: Stores data into a Berkeley DB database. See the ovdb(5) man page.

storeonxref

If set to true, articles will be stored based on the newsgroup names in the Xref: header rather than in the Newsgroups: header. This affects what the patterns in storage.conf apply to. The primary interesting effect of setting this to true is to enable filing of all control messages according to what storage class the control pseudogroups are filed in rather than according to the newsgroups the control messages are posted to. This is a boolean value and the default is false.

useoverchan

Whether to create overview data innd(8) internally through libstorage(3). If set to false, innd create overview data by itself. If set to true, innd does not create. In the case, you need to run overchan(8) by creating entry in newsfeeds(5). Setting to true may be useful, if innd can not keep up with incoming feed and the bottle neck is creating overview data within innd. This is a boolean value and the default is false.

wireformat

Only used with the tradspool storage method, this says whether to write articles in wire format. Wire format means storing articles with at the end of each line and with periods at the beginning of lines doubled, the article format required by the NNTP protocol. Articles stored in this format are suitable for sending directly to a network connection without requiring conversion, and therefore setting this to true can make the server more efficient. The primary reason not to set this is if you have old existing software that looks around in the spool and doesn`t understand how to read wire format. Storage methods other than tradspool always store articles in wire format. This is a boolean value and the default is false.

xrefslave

Whether to act as the slave of another server. If set, INN attempts to duplicate exactly the article numbering of the server feeding it by looking at the Xref: header of incoming articles and assigning the same article numbers to articles as was noted in the Xref: header from the upstream server. The result is that clients should be able to point at either server interchangeably (using some load balancing scheme, for example) and see the same internal article numbering. Servers with this parameter set should generally only have one upstream feed, and should always have nnrpdposthost set to hand locally posted articles off to the master server. This is a boolean value and the default is false.

Reading

These parameters affect the behavior of INN for readers. Most of them are used by nnrpd(8). There are some special sets of settings that are broken out separately after the initial alphabetized list.

allownewnews: Whether to allow use of the NEWNEWS command by clients. This command used to put a heavy load on the server in older versions of INN, but is now reasonably efficient, at least if only one newsgroup is specified by the client. This is a boolean value and the default is true. If you use the access parameter in readers.conf(5), be sure to read about the way it overrides allownewnews.
articlemmap: Whether to attempt to mmap() articles. Setting this to true will give better performance on most systems, but some systems have problems with mmap(). If this is set to false, articles will be read into memory before being sent to readers. This is a boolean value and the default is false.
clienttimeout: How long (in seconds) a client connection can be idle before it exits. When setting this parameter, be aware that some newsreaders use the same connection for reading and posting and don`t deal well with the connection timing out while a post is being composed. If the system isn`t having a problem with too many long-lived connections, it may be a good idea to increase this value to 3600 (an hour). The default value is 600 (ten minutes).
nnrpdcheckart: Whether nnrpd(8) should check the existence of an article before listing it as present in response to an NNTP command. The primary use of this setting is to prevent nnrpd from returning information about articles which are no longer present on the server but which still have overview data available. Checking the existence of articles before returning overview information slows down the overview commands, but reduces the number of ``article is missing`` errors seen by the client. This is a boolean value and the default is true.
nnrpperlauth: Whether to use the Perl hook in nnrpd(8) to authenticate readers. If this is enabled, normal readers.conf(5) authentication will not be used, and instead the Perl hook will be called to authenticate connections. This is a boolean value and the default is false.
nnrppythonauth: Whether to use the Python hook in nnrpd(8) to authenticate readers. If this is enabled, normal readers.conf(5) authentication will not be used, and instead the python hook will be called to authenticate connections. This is a boolean value and the default is false.
noreader: Normally, innd(8) will fork a copy of nnrpd(8) for all incoming connections from hosts not listed in incoming.conf. If this parameter is set to true, those connections will instead be rejected with a 502 error code. This should be set to true for a transit-only server that doesn`t support readers, if nnrpd is being started out of inetd, or if nnrpd is run in daemon mode. This is a boolean value and the default is false.
readerswhenstopped: Whether to allow readers to connect even if the server is paused or throttled. This is only applicable if nnrpd(8) is spawned from innd(8) rather than run out of inetd or in daemon mode. This is a boolean value and the default is false.
readertrack: Whether to enable the tracking system for client behavior. Tracked information is recoreded to pathlog/tracklogs/log-ID. ID is determined by nnrpd`s PID and when nnrpd runs. Currenlty that information includes the messages which tell enabling reader track and where posted article is tracked. Which user and client, that is recorded, is determined by nnrpd.track. See nnrpd.track(5) for more information. This is a boolean value and the default is false.

INN has optional support for generating keyword information automatically from article body text and putting that information in overview for the use of clients that know to look for it. The following parameters control that feature.

This may be too slow if you`re taking a substantial feed, and probably will not be useful for the average news reader; enabling this is not recommended unless you have some specific intention to take advantage of it.

keywords: Whether the keyword generation support should be enabled. This is a boolean value and the default is false.
FIXME: Currently, support for keyword generation is configured into INN semi-randomly (based on whether configure found the regex library); it should be an option to configure and that option should be mentioned here.
keyartlimit: Articles larger than this value in bytes will not have keywords generated for them (since it would take too long to do so). The default value is 100000 (approximately 100KB).
keylimit: Maximum number of bytes allocated for keyword data. If there are more keywords than will fit, separated by commas, into this many bytes, the rest are discarded. The default value is 512.
keymaxwords: Maximum number of keywords that will be generated for an article. (The keyword generation code will attempt to discard ``noise`` words, so the number of keywords actually writen into the overview will usually be smaller than this even if the maximum number of keywords is found.) The default value is 250.

Posting

These parameters are only used by nnrpd(8), inews(1), and other programs that accept or generate postings. There are some special sets of settings that are broken out separately after the initial alphabetized list.

addnntppostingdate: Whether to add an NNTP-Posting-Date: header to all local posts. This is a boolean value and the default is true.
addnntppostinghost: Whether to add an NNTP-Posting-Host: header to all local posts giving the FQDN or IP address of the system from which the post was received. This is a boolean value and the default is true.
checkincludedtext: Whether to check local postings for the ratio of new to quoted text and reject them if that ratio is under 50%. Included text is recognized by looking for lines beginning with ">", "|", or ":". This is a boolean value and the default is false.
complaints: The value of the X-Complaints-To: header added to all local posts. The default is the newsmaster`s e-mail address. (If the newsmaster, selected at configure time and defaulting to "usenet", doesn`t contain "@", the address will consist of the newsmaster, a "@", and the value of fromhost.)
fromhost: Contains a domain used to construct e-mail addresses. The address of the local news administrator will be given as <user>@fromhost, where <user> is the newsmaster user set at compile time ("usenet" by default). This setting will also be used by mailpost(8) to fully qualify addresses and by inews(1) to generate the Sender: header (and From: header if missing). The value of the FROMHOST environment variable, if set, overrides this setting. The default is the fully-qualified domain name of the local host.
localmaxartsize: The maximum article size (in bytes) for locally posted articles. Articles larger than this will be rejected. Also see maxartsize. The default value is 1000000 (approximately 1MB).
moderatormailer: The address to which to send submissions for moderated groups. It is only used if the moderators file doesn`t exist, or if the moderated group to which an article is posted is not matched by any entry in that file, and takes the same form as an entry in the moderators file. In most cases, "%s@moderators.isc.org" is a good value for this parameter (%s is expanded into a form of the newsgroup name). See moderators(5) for more details about the syntax. The default is unset. If this parameter isn`t set and an article is posted to a moderated group that does not have a matching entry in the moderators file, the posting will be rejected with an error.
nnrpdauthsender: Whether to generate a Sender: header based on reader authentication. If this parameter is set, a Sender: header will be added to local posts containing the authenticated user name and the reader`s hostname. If this is enabled but authentication does not return a username, the Sender: header will be removed from all posts even if the poster includes one. This is a boolean value and the default is false.
nnrpdposthost: If set, nnrpd(8) and rnews(1) will pass all locally posted articles to the specified host rather than trying to inject them locally. This should always be set if xrefslave is true. The default value is unset.
nnrpdpostport: The port on the remote server to connect to to post when nnrpdposthost is used. The default value is 119.
organization: What to put in the Organization: header if it is left blank by the poster. The value of the ORGANIZATION environment variable, if set, overrides this setting. The default is unset, which tells INN not to insert an Organization: header.
spoolfirst: If true, nnrpd(8) will spool new articles rather than attempting to send them to innd(8). If false, nnrpd will spool articles only if it receives an error trying to send them to innd. Setting this to true can be useful if nnrpd must respond as fast as possible to the client; however, when set, articles will not appear to readers until they are given to innd. nnrpd won`t do this; "rnews -U" must be run periodically to take the spooled articles and post them. This is a boolean value and the default is false.
strippostcc: Whether to strip To:, Cc:, and Bcc: headers out of all local posts via nnrpd(8). The primary purpose of this setting is to prevent abuse of the news server by posting to a moderated group and including To: or Cc: headers in the post so that the news server will send the article to arbitrary addresses. INN now protects against this abuse in other ways provided mta is set to a command that includes %s and honors it, so this is generally no longer needed. This is a boolean value and the default is false.

nnrpd(8) has support for controlling high-volume posters via an exponential backoff algorithm, as configured by the following parameters.

Exponential posting backoff works as follows: News clients are indexed by IP address (or username, see backoffauth below). Each time a post is received from an IP address, the time of posting is stored (along with the previous sleep time, see below). After a configurable number of posts in a configurable period of time, nnrpd(8) will activate posting backoff and begin to sleep for increasing periods of time before actually posting anything. Posts will still be accepted, but an increasingly reduced rate.

After backoff has been activated, the length of time to sleep is computed based on the difference in time between the last posting and the current posting. If this difference is less than backoffpostfast, the new sleep time will be 1 + (previous sleep time * backoffk). If this difference is less than backoffpostslow but greater than backoffpostfast, then the new sleep time will equal the previous sleep time. If this difference is greater than backoffpostslow, the new sleep time is zero and posting backoff is deactivated for this poster.

Exponential posting backoff will not be enabled unless backoffdb is set and backoffpostfast and backoffpostslow are set to something other than their default values.

Here are the parameters that control exponential posting backoff:

backoffauth: Whether to index posting backoffs by user rather than by source IP address. You must be using authentication in nnrpd(8) for a value of true to have any meaning. This is a boolean value and the default is false.
backoffdb: The path to a directory, writeable by the news user, that will contain the backoff database. There is no default for this parameter; you must provide a path to an existing and writeable directory to enable exponential backoff.
backoffk: The amount to multiply the previous sleep time by if the user is still posting too quickly. A value of 2 will double the sleep time for each excessive post. The default value is 1.
backoffpostfast: Postings from the same identity that arrive in less than this amount of time (in seconds) will trigger increasing sleep time in the backoff algorithm. The default value is 0.
backoffpostslow: Postings from the same identity that arrive in greater than this amount of time (in seconds) will reset the backoff algorithm. Another way to look at this constant is to realize that posters will be allowed to post 86400/backoffpostslow posts per day. The default value is 1.
backofftrigger: This many postings are allowed before the backoff algorithm is triggered. The default value is 10000.

Monitoring

These parameters control the behavior of innwatch(8), the program that monitors INN and informs the news administrator if anything goes wrong with it.

doinnwatch: Whether to start innwatch(8) from rc.news. This is a boolean value, and the default is true.
innwatchbatchspace: Free space in pathoutgoing, in inndf(8) output units, at which innd(8) will be throttled by innwatch(8), assuming a default innwatch.ctl(5). The default value is 800.
innwatchlibspace: Free space in pathdb, in inndf(8) output units, at which innd(8) will be throttled by innwatch(8), assuming a default innwatch.ctl(5). The default value is 25000.
innwatchloload: Load average times 100 at innd(8) will be restarted by innwatch(8) (undoing a previous pause or throttle), assuming a default innwatch.ctl(5). The default value is 1000.
innwatchhiload: Load average times 100 at which innd(8) will be throttled by innwatch(8), assuming a default innwatch.ctl(5). The default value is 2000.
innwatchpauseload: Load average times 100 at which innd(8) will be paused by innwatch(8), assuming a default innwatch.ctl(5). The default value is 1500.
innwatchsleeptime: How long (in seconds) innwatch(8) will sleep between each check of INN. The default value is 600.
innwatchspoolnodes: Free inodes in patharticles at which innd(8) will be throttled by innwatch(8), assuming a default innwatch.ctl(5). The default value is 200.
innwatchspoolspace: Free space in patharticles and pathoverview, in inndf(8) output units, at which innd(8) will be throttled by innwatch(8), assuming a default innwatch.ctl(5). The default value is 8000.

Logging

These parameters control what information INN logs.

docnfsstat: Whether to start cnfsstat(8) when innd(8) is started. cnfsstat will log the status of all CNFS cycbuffs to syslog on a periodic basis. This is a boolean value and the default is false.
logartsize: Whether the size of accepted articles (in bytes) should be written to the article log file. This is useful for flow rate statistics and is recommended. This is a boolean value and the default is true.
logcancelcomm: Set this to true to log "ctlinnd cancel" commands to syslog. This is a boolean value and the default is false.
logcycles: How many old logs scanlogs(8) keeps. scanlogs(8) is generally run by news.daily(8) and will archive compressed copies of this many days worth of old logs. The default value is 3.
logipaddr: Whether the verified name of the remote feeding host should be logged to the article log for incoming articles rather than the last entry in the Path: header. The only reason to ever set this to false is due to some interactions with newsfeeds flags; see newsfeeds(5) for more information. This is a boolean value and the default is true.
logsitename: Whether the names of the sites to which accepted articles will be sent should be put into the article log file. This is useful for debugging and statistics and can be used by newsrequeue(8). This is a boolean value and the default is true.
nnrpdoverstats: Whether nnrpd overview statistics should be logged via syslog. This can be useful for measuring overview performance. This is a boolean value and the default is false.
nntpactsync: How many articles to process on an incoming channel before logging the activity. The default value is 200.
FIXME: This is a rather unintuitive name for this parameter.
nntplinklog: Whether to put the storage API token for accepted articles (used by nntplink) in the article log. This is a boolean value and the default is false.
status: How frequently (in seconds) innd(8) should write out a status report. The report is written to pathhttp/inn_status.html. If this is set to 0 or "false", status reporting is disabled. The default value is 0.
timer: How frequently (in seconds) innd(8) should report performance timings to syslog. If this is set to 0 or "false", performance timing is disabled. Enabling this is highly recommended, and innreport(8) can produce a nice summary of the timings. The default value is 0.

System Tuning

The following parameters can be modified to tune the low-level operation of INN. In general, you shouldn`t need to modify any of them except possibly rlimitnofile unless the server is having difficulty.

badiocount: How many read or write failures until a channel is put to sleep or closed. The default value is 5.
blockbackoff: Each time an attempted write returns EAGAIN or EWOULDBLOCK, innd(8) will wait for an increasing number of seconds before trying it again. This is the multiplier for the sleep time. If you`re having trouble with channel feeds not keeping up, it may be good to change this value to 2 or 3, since then when the channel fills INN will try again in a couple of seconds rather than waiting two minutes. The default value is 120.
chaninacttime: The time (in seconds) to wait between noticing inactive channels. The default value is 600.
chanretrytime: How many seconds to wait before a channel restarts. The default value is 300.
icdsynccount: How many article writes between updating the active and history files. The default value is 10.
maxforks: How many times to attempt a fork(2) before giving up. The default value is 10.
nicekids: If set to anything other than 0, all child processes of innd(8) will have this nice(2) value. This is usually used to give all child processes of innd(8) a lower priority (higher nice value) so that innd(8) can get the lion`s share of the CPU when it needs it. The default value is 4.
nicenewnews: If set to anything greater than 0, all nnrpd(8) processes that receive and process a NEWNEWS command will nice(2) themselves to this value (giving other nnrpd processes a higher priority). The default value is 0. Note that this value will be ignored if set to a lower value than nicennrpd (or nicekids if nnrpd(8) is spawned from innd(8)).
nicennrpd: If set to anything greater than 0, all nnrpd(8) processes will nice(1) themselves to this value. This gives other news processes a higher priority and can help overchan(8) keep up with incoming news (if that`s the object, be sure overchan(8) isn`t also set to a lower priority via nicekids). The default value is 0, which will cause nnrpd(8) processes spawned from innd(8) to use the value of nicekids and nnrpd(8) run as a daemon to use the system default priority. Note that for nnrpd(8) processes spawned from innd(8), this value will be ignored if set to a value lower than nicekids.
pauseretrytime: Wait for this many seconds before noticing inactive channels. Wait for this many seconds before innd processes article when it`s paused or the number of channel write failure exceeds badiocount. The default value is 300.
peertimeout: How long (in seconds) an innd(8) incoming channel may be inactive before innd closes it. The default value is 3600 (an hour).
rlimitnofile: The maximum number of file descriptors that innd(8) or innfeed(8) can have open at once. If innd(8) or innfeed(8) attempts to open more file descriptors than this value, it is possible the program may throttle or otherwise suffer reduced functionality. The number of open file descriptors is roughly the maximum number of incoming feeds and outgoing batches for innd(8) and the number of outgoing streams for innfeed(8). If this parameter is set to a negative value, the default limit of the operating system will be used; this will normally be adequate on systems other than Solaris. Nearly all operating systems have some hard maximum limit beyond which this value cannot be raised, usually either 128, 256, or 1024. The default value of this parameter is -1. Setting it to 256 on Solaris systems is highly recommended.

Paths and File Names

patharchive: Where to store archived news. The default value is pathspool/archive.
patharticles: The path to where the news articles are stored (for storage methods other than CNFS). The default value is pathspool/spool.
pathbin: The path to the news binaries. The default value is pathnews/bin.
pathcontrol: The path to the files that handle control messages. If you are using controlchan(8) (usecontrolchan is set), the code for handling each separate type of control message is located here. If you are using INN`s built-in control message handling, each executable file in this directory represents a handler for the Control: message with the same name as that file. Be very careful what you put in this directory executable, as it can potentially be a severe security risk. The default value is pathbin/control.
pathdb: The path to the database files used and updated by the server (currently, active, active.times, history and its indices, and newsgroups). The default value is pathnews/db.
pathetc: The path to the news configuration files. The default value is pathnews/etc.
pathfilter: The path to the Perl, Tcl, and Python filters. The default value is pathbin/filter.
pathhttp: Where any HTML files (such as periodic status reports) are placed. If the news reports should be available in real-time on the web, the files in this directory should be served by a web server. The default value is the value of pathlog.
pathincoming: Location where incoming batched news is stored. The default value is pathspool/incoming.
pathlog: Where the news log files are written. The default value is pathnews/log.
pathnews: The home directory of the news user and usually the root of the news hierarchy. There is no default; this parameter must be set in inn.conf or INN will refuse to start.
pathoutgoing: Default location for outgoing feed files. The default value is pathspool/outgoing.
pathoverview: The path to news overview files. The default value is pathspool/overview.
pathrun: The path to files required while the server is running and run-time state information. This includes lock files and the sockets for communicating with innd(8). This directory and the control sockets in it should be protected from unprivileged users other than the news user. The default value is pathnews/run.
pathspool: The root of the news spool hierarchy. This used mostly to set the defaults for other parameters, and to determine the path to the backlog directory for innfeed(8). The default value is pathnews/spool.
pathtmp: Where INN puts temporary files. For security reasons, this is not the same as the system temporary files directory (INN creates a lot of temporary files with predictable names and does not go to particularly great lengths to protect against symlink attacks and the like; this is safe provided that normal users can`t write into its temporary directory). It must be on the same partition as pathincoming for rnews(1) to work correctly. The default value is set at configure time and defaults to pathnews/tmp.

EXAMPLE

Here is a very minimalist example that only sets those parameters that are required.

mta: /usr/lib/sendmail -oi -oem %s ovmethod: tradindexed pathhost: news.example.com pathnews: /usr/local/news

For a more comprehensive example, see the sample inn.conf distributed with INN and installed as a starting point; it contains all of the default values for reference.

HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews and since modified, updated, and reorganized by innumerable other people.

$Id: inn.conf.5,v 1.86.2.11 2002/09/08 18:08:17 vinocur Exp $

innwatch.ctl

NAME

innwatch.ctl - control Usenet supervision by innwatch

DESCRIPTION

The file <pathetc in inn.conf>/innwatch.ctl is used to determine what actions are taken during the periodic supervisions by innwatch.

The file consists of a series of lines; blank lines and lines beginning with a number sign (``#``) are ignored. All other lines consist of seven fields, each preceded by a delimiting character:

: :label:state:condition:test:limit:command:reason

The delimiter can be any one of several non-alphanumeric characters that does not appear elsewhere in the line; there is no way to quote it to include it in any of the fields. Any of ``!``, ``,``, ``:``, ``@``, ``;``, or ``?`` is a good choice. Each line can have a different delimiter; the first character on each line is the delimiter for that line. White space surrounding delimiters, except before the first, is ignored, and does not form part of the fields, white space within fields is permitted. All delimiters must be present.

The first field is a label for the control line. It is used as an internal state indicator and in ctlinnd messages to control the server. If omitted, the line number is used.

The second field specifies when this control line should be used. It consists of a list of labels, and special indicators, separated by whitespace. If the current state matches against any of the labels in this field, this line will be used as described below. The values that may be used are:

-: This line matches if the current state is the same as the label on this line, or if the current state is ``run,`` the initial state. This is also the default state if this field is empty.
+: This line matches if the current state is ``run.``
*: This line always matches.
label: This line matches if the current state is the specified ``label.``
-label: This line matches if the current state is not the specified ``label.``

The third field specifies a shell command that is invoked if this line matches. Do not use any shell filename expansion characters such as ``*``, ``?``, or ``[`` (even quoted, they`re not likely to work as intended). If the command succeeds, as indicated by its exit status, it is expected to have printed a single integer to standard output. This gives the value of this control line, to be used below. If the command fails, the line is ignored. The command is executed with its current directory set to the news spool directory, <patharticles in inn.conf>.

The fourth field specifies the operator to use to test the value returned above. It should be one of the two letter numeric test operators defined in test(1) such as ``eq``, ``lt`` and the like. The leading dash (``-``) should not be included.

The fifth field specifies a constant with which to compare the value using the operator just defined. This is done by invoking the command:

: test value -operator constant

The line is said to ``succeed`` if it returns true.

The sixth field specifies what should be done if the line succeeds, and in some cases if it fails. Any of the following words may be used:

throttle: Causes innwatch to throttle the server if this line succeeds. It also sets the state to the value of the line`s label. If the line fails, and the state was previously equal to the label on this line (that is, this line had previously succeeded), then a go command will be sent to the server, and innwatch will return to the ``run`` state. The ``throttle`` is only performed if the current state is ``run`` or a state other than the label of this line, regardless of whether the command succeeds.
pause: Is identical to ``throttle`` except that the server is paused.
shutdown: Sends a ``shutdown`` command to the server. It is for emergency use only.
flush: Sends a ``flush`` command to the server.
go: Causes innwatch to send a ``go`` command to the server and to set the state to ``run.``
exit: Causes innwatch to exit.

skip: The result of the control file is skipped for the current pass.

The last field specifies the reason that is used in those ctlinnd commands that require one. More strictly, it is part of the reason --- innwatch appends some information to it. In order to enable other sites to recognize the state of the local innd server, this field should usually be set to one of several standard values. Use ``No space`` if the server is rejecting articles because of a lack of filesystem resources. Use ``loadav`` if the server is rejecting articles because of a lack of CPU resources.

Once innwatch has taken some action as a consequence of its control line, it skips the rest of the control file for this pass. If the action was to restart the server (that is, issue a ``go`` command), then the next pass will commence almost immediately, so that innwatch can discover any other condition that may mean that the server should be suspended again.

EXAMPLES

: @@@inndf .@lt@10000@throttle@No space @@@inndf -i .@lt@1000@throttle@No space (inodes)

The first line causes the server to be throttled if the free space drops below 10000 units (using whatever units inndf(8) uses), and restarted again when free space increases above the threshold.

The second line does the same for inodes.

The next three lines act as a group and should appear in the following order. It is easier to explain them, however, if they are described from the last up.

: !load!load hiload!loadavg!lt!5!go! :hiload:+ load:loadavg:gt:8:throttle:loadav /load/+/loadavg/ge/6/pause/loadav

The final line causes the server to be paused if innwatch is in the ``run`` state and the load average rises to, or above, six. The state is set to ``load`` when this happens. The previous line causes the server to be throttled when innwatch is in the ``run`` or ``load`` state, and the load average rises above eight. The state is set to ``hiload`` when this happens. Note that innwatch can switch the server from ``paused`` to ``throttled`` if the load average rises from below six to between six and seven, and then to above eight. The first line causes the server to be sent a ``go`` command if innwatch is in the ``load`` or ``hiload`` state, and the load average drops below five.

Note that all three lines assume a mythical command loadavg that is assumed to print the current load average as an integer. In more practical circumstances, a pipe of uptime into awk is more likely to be useful.

BUGS

This file must be tailored for each individual site, the sample supplied is truly no more than a sample. The file should be ordered so that the more common problems are tested first.

The ``run`` state is not actually identified by the label with that three letter name, and using it will not work as expected.

Using an ``unusual`` character for the delimiter such as ``(``, ``*``, ``&``, `````, ``´``, and the like, is likely to lead to obscure and hard to locate bugs.

HISTORY

Written by <kre@munnari.oz.au> for InterNetNews. This is revision 1.7.4.1, dated 2000/08/17.

ipc

NAME

ipc - System V interprocess communication mechanisms

SYNOPSIS

# include <sys/types.h> # include <sys/ipc.h> # include <sys/msg.h> # include <sys/sem.h> # include <sys/shm.h>

DESCRIPTION

This manual page refers to the Linux implementation of the System V interprocess communication mechanisms: message queues, semaphore sets, and shared memory segments. In the following, the word resource means an instantiation of one among such mechanisms.

Resource Access Permissions

For each resource, the system uses a common structure of type struct ipc_perm to store information needed in determining permissions to perform an ipc operation. The ipc_perm structure, defined by the <sys/ipc.h> system header file, includes the following members:

       ushort cuid;     /* creator user id */

       ushort cgid;     /* creator group id */

       ushort uid;      /* owner user id */

       ushort gid;      /* owner group id */

       ushort mode;     /* r/w permissions */

The mode member of the ipc_perm structure defines, with its lower 9 bits, the access permissions to the resource for a process executing an ipc system call. The permissions are interpreted as follows:

0400 Read by user. 0200 Write by user. 0040 Read by group. 0020 Write by group. 0004 Read by others. 0002 Write by others.

Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. Furthermore, "write" effectively means "alter" for a semaphore set.

The same system header file also defines the following symbolic constants:

IPC_CREAT: Create entry if key doesn`t exist.
IPC_EXCL: Fail if key exists.
IPC_NOWAIT: Error if request must wait.
IPC_PRIVATE: Private key.
IPC_RMID: Remove resource.
IPC_SET: Set resource options.
IPC_STAT: Get resource options.

Note that IPC_PRIVATE is a key_t type, while all the other symbolic constants are flag fields and can be OR`ed into an int type variable.

Message Queues

A message queue is uniquely identified by a positive integer (its msqid) and has an associated data structure of type struct msqid_ds, defined in <sys/msg.h>, containing the following members:

       struct ipc_perm msg_perm;
       ushort msg_qnum;         /* no of messages on queue */

       ushort msg_qbytes;       /* bytes max on a queue */

       ushort msg_lspid;        /* pid of last msgsnd call */

       ushort msg_lrpid;        /* pid of last msgrcv call */

       time_t msg_stime;        /* last msgsnd time */

       time_t msg_rtime;        /* last msgrcv time */

       time_t msg_ctime;        /* last change time */

msg_perm: ipc_perm structure that specifies the access permissions on the message queue.
msg_qnum: Number of messages currently on the message queue.
msg_qbytes: Maximum number of bytes of message text allowed on the message queue.
msg_lspid: ID of the process that performed the last msgsnd system call.
msg_lrpid: ID of the process that performed the last msgrcv system call.
msg_stime: Time of the last msgsnd system call.
msg_rtime: Time of the last msgcv system call.
msg_ctime: Time of the last system call that changed a member of the msqid_ds structure.

Semaphore Sets

A semaphore set is uniquely identified by a positive integer (its semid) and has an associated data structure of type struct semid_ds, defined in <sys/sem.h>, containing the following members:

       struct ipc_perm sem_perm;
       time_t sem_otime;        /* last operation time */

       time_t sem_ctime;        /* last change time */

       ushort sem_nsems;        /* count of sems in set */

sem_perm: ipc_perm structure that specifies the access permissions on the semaphore set.
sem_otime: Time of last semop system call.
sem_ctime: Time of last semctl system call that changed a member of the above structure or of one semaphore belonging to the set.
sem_nsems: Number of semaphores in the set. Each semaphore of the set is referenced by a non-negative integer ranging from 0 to sem_nsems-1.

A semaphore is a data structure of type struct sem containing the following members:

       ushort semval;   /* semaphore value */

       short sempid;    /* pid for last operation */

       ushort semncnt; /* nr awaiting semval to increase */

       ushort semzcnt; /* nr awaiting semval = 0 */

semval: Semaphore value: a non-negative integer.
sempid: ID of the last process that performed a semaphore operation on this semaphore.
semncnt: Number of processes suspended awaiting for semval to increase.
semznt: Number of processes suspended awaiting for semval to become zero.

Shared Memory Segments

A shared memory segment is uniquely identified by a positive integer (its shmid) and has an associated data structure of type struct shmid_ds, defined in <sys/shm.h>, containing the following members:

       struct ipc_perm shm_perm;
       int shm_segsz; /* size of segment */

       ushort shm_cpid;         /* pid of creator */

       ushort shm_lpid;         /* pid, last operation */

       short shm_nattch;        /* no. of current attaches */

       time_t shm_atime;        /* time of last attach */

       time_t shm_dtime;        /* time of last detach */

       time_t shm_ctime;        /* time of last change */

shm_perm: ipc_perm structure that specifies the access permissions on the shared memory segment.
shm_segsz: Size in bytes of the shared memory segment.
shm_cpid: ID of the process that created the shared memory segment.
shm_lpid: ID of the last process that executed a shmat or shmdt system call.
shm_nattch: Number of current alive attaches for this shared memory segment.
shm_atime: Time of the last shmat system call.
shm_dtime: Time of the last shmdt system call.
shm_ctime: Time of the last shmctl system call that changed shmid_ds.

ipsec.secrets

NAME

ipsec.secrets - secrets for IKE/IPsec authentication

DESCRIPTION

The file ipsec.secrets holds a table of secrets. These secrets are used by ipsec_pluto(8), the Open Internet Key Exchange daemon, to authenticate other hosts. Currently there are two kinds of secrets: preshared secrets and RSA private keys.

It is vital that these secrets be protected. The file should be owned by the super-user, and its permissions should be set to block all access by others.

The file is a sequence of entries and include directives. Here is an example. Each entry or directive must start at the left margin, but if it continues beyond a single line, each continuation line must be indented.

: # sample /etc/ipsec.secrets file for 10.1.0.1 10.1.0.1 10.2.0.1: PSK "secret shared by two hosts" # an entry may be split across lines, # but indentation matters www.xs4all.nl @www.kremvax.ru 10.6.0.1 10.7.0.1 1.8.0.1: PSK "secret shared by 5" # an RSA private key. # note that the lines are too wide for a # man page, so ... has been substituted for # the truncated part @my.com: rsa { Modulus: 0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt... PublicExponent: 0sAw== PrivateExponent: 0shlGbVR1m8Z+7rhzSyenCaBN... Prime1: 0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l... Prime2: 0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0... Exponent1: 0soaXj85ihM5M2inVf/NfHmtLutVz4r... Exponent2: 0sjdAL9VFizF+BKU4ohguJFzOd55OG6... Coefficient: 0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ... } include ipsec.*.secrets # get secrets from other files

Each entry in the file is a list of indices, followed by a secret. The two parts are separated by a colon (:) that is followed by whitespace or a newline. For compatability with the previous form of this file, if the key part is just a double-quoted string the colon may be left out.

An index is an IP address, or a Fully Qualified Domain Name, user@FQDN, %any or %any6 (other kinds may come). An IP address may be written in the familiar dotted quad form or as a domain name to be looked up when the file is loaded (or in any of the forms supported by the Openswan ipsec_ttoaddr(3) routine). In many cases it is a bad idea to use domain names because the name server may not be running or may be insecure. To denote a Fully Qualified Domain Name (as opposed to an IP address denoted by its domain name), precede the name with an at sign (@).

Matching IDs with indices is fairly straightforward: they have to be equal. In the case of a ``Road Warrior`` connection, if an equal match is not found for the Peer`s ID, and it is in the form of an IP address, an index of %any will match the peer`s IP address if IPV4 and %any6 will match a the peer`s IP address if IPV6. Currently, the obsolete notation 0.0.0.0 may be used in place of %any.

An additional complexity arises in the case of authentication by preshared secret: the responder will need to look up the secret before the Peer`s ID payload has been decoded, so the ID used will be the IP address.

To authenticate a connection between two hosts, the entry that most specifically matches the host and peer IDs is used. An entry with no index will match any host and peer. More specifically, an entry with one index will match a host and peer if the index matches the host`s ID (the peer isn`t considered). Still more specifically, an entry with multiple indices will match a host and peer if the host ID and peer ID each match one of the indices. If the key is for an asymmetric authentication technique (i.e. a public key system such as RSA), an entry with multiple indices will match a host and peer even if only the host ID matches an index (it is presumed that the multiple indices are all identities of the host). It is acceptable for two entries to be the best match as long as they agree about the secret or private key.

Authentication by preshared secret requires that both systems find the identical secret (the secret is not actually transmitted by the IKE protocol). If both the host and peer appear in the index list, the same entry will be suitable for both systems so verbatim copying between systems can be used. This naturally extends to larger groups sharing the same secret. Thus multiple-index entries are best for PSK authentication.

Authentication by RSA Signatures requires that each host have its own private key. A host could reasonably use a different private keys for different interfaces and for different peers. But it would not be normal to share entries between systems. Thus thus no-index and one-index forms of entry often make sense for RSA Signature authentication.

The key part of an entry may start with a token indicating the kind of key. ``RSA`` signifies RSA private key and ``PSK`` signifies PreShared Key (case is ignored). For compatability with previous forms of this file, PSK is the default.

A preshared secret is most conveniently represented as a sequence of characters, delimited by the double-quote character ("). The sequence cannot contain a newline or double-quote. Strictly speaking, the secret is actually the sequence of bytes that is used in the file to represent the sequence of characters (excluding the delimiters). A preshared secret may also be represented, without quotes, in any form supported by ipsec_ttodata(3).

An RSA private key is a composite of eight generally large numbers. The notation used is a brace-enclosed list of field name and value pairs (see the example above). A suitable key, in a suitable format, may be generated by ipsec_rsasigkey(8). The structure is very similar to that used by BIND 8.2.2 or later, but note that the numbers must have a ``0s`` prefix if they are in base 64. The order of the fields is fixed.

The first token an entry must start in the first column of its line. Subsequent tokens must be separated by whitespace, except for a colon token, which only needs to be followed by whitespace. A newline is taken as whitespace, but every line of an entry after the first must be indented.

Whitespace at the end of a line is ignored (except in the 0t notation for a key). At the start of line or after whitespace, # and the following text up to the end of the line is treated as a comment. Within entries, all lines must be indented (except for lines with no tokens). Outside entries, no line may be indented (this is to make sure that the file layout reflects its structure).

An include directive causes the contents of the named file to be processed before continuing with the current file. The filename is subject to ``globbing`` as in sh(1), so every file with a matching name is processed. Includes may be nested to a modest depth (10, currently). If the filename doesn`t start with a /, the directory containing the current file is prepended to the name. The include directive is a line that starts with the word include, followed by whitespace, followed by the filename (which must not contain whitespace).

FILES

/etc/ipsec.secrets

HISTORY

Originally designed for the FreeS/WAN project <http://www.freeswan.org> by D. Hugh Redelmeier.

BUGS

If an ID is 0.0.0.0, it will match %any; if it is 0::0, it will match %any6.

ipsec_ipsec.conf

NAME

ipsec.conf - IPsec configuration and connections

DESCRIPTION

The optional ipsec.conf file specifies most configuration and control information for the FreeS/WAN IPsec subsystem. (The major exception is secrets for authentication; see ipsec.secrets(5).) Its contents are not security-sensitive unless manual keying is being done for more than just testing, in which case the encryption/authentication keys in the descriptions for the manually-keyed connections are very sensitive (and those connection descriptions are probably best kept in a separate file, via the include facility described below).

The file is a text file, consisting of one or more sections. White space followed by # followed by anything to the end of the line is a comment and is ignored, as are empty lines which are not within a section.

A line which contains include and a file name, separated by white space, is replaced by the contents of that file, preceded and followed by empty lines. If the file name is not a full pathname, it is considered to be relative to the directory containing the including file. Such inclusions can be nested. Only a single filename may be supplied, and it may not contain white space, but it may include shell wildcards (see sh(1)); for example:

include ipsec.*.conf

The intention of the include facility is mostly to permit keeping information on connections, or sets of connections, separate from the main configuration file. This permits such connection descriptions to be changed, copied to the other security gateways involved, etc., without having to constantly extract them from the configuration file and then insert them back into it. Note also the also and alsoflip parameters (described below) which permit splitting a single logical section (e.g. a connection description) into several actual sections.

The first significant line of the file must specify the version of this specification that it conforms to:

version 2

A section begins with a line of the form:

type name

where type indicates what type of section follows, and name is an arbitrary name which distinguishes the section from others of the same type. (Names must start with a letter and may contain only letters, digits, periods, underscores, and hyphens.) All subsequent non-empty lines which begin with white space are part of the section; comments within a section must begin with white space too. There may be only one section of a given type with a given name.

Lines within the section are generally of the form

parameter=value

(note the mandatory preceding white space). There can be white space on either side of the =. Parameter names follow the same syntax as section names, and are specific to a section type. Unless otherwise explicitly specified, no parameter name may appear more than once in a section.

An empty value stands for the system default value (if any) of the parameter, i.e. it is roughly equivalent to omitting the parameter line entirely. A value may contain white space only if the entire value is enclosed in double quotes ("); a value cannot itself contain a double quote, nor may it be continued across more than one line.

Numeric values are specified to be either an ``integer`` (a sequence of digits) or a ``decimal number`` (sequence of digits optionally followed by `.` and another sequence of digits).

There is currently one parameter which is available in any type of section:

also: the value is a section name; the parameters of that section are appended to this section, as if they had been written as part of it. The specified section must exist, must follow the current one, and must have the same section type. (Nesting is permitted, and there may be more than one also in a single section, although it is forbidden to append the same section more than once.) This allows, for example, keeping the encryption keys for a connection in a separate file from the rest of the description, by using both an also parameter and an include line. (Caution, see BUGS below for some restrictions.)
alsoflip: can be used in a conn section. It acts like an also that flips the referenced section`s entries left-for-right.

Parameter names beginning with x- (or X-, or x_, or X_) are reserved for user extensions and will never be assigned meanings by IPsec. Parameters with such names must still observe the syntax rules (limits on characters used in the name; no white space in a non-quoted value; no newlines or double quotes within the value). All other as-yet-unused parameter names are reserved for future IPsec improvements.

A section with name %default specifies defaults for sections of the same type. For each parameter in it, any section of that type which does not have a parameter of the same name gets a copy of the one from the %default section. There may be multiple %default sections of a given type, but only one default may be supplied for any specific parameter name, and all %default sections of a given type must precede all non-%default sections of that type. %default sections may not contain also or alsoflip parameters.

Currently there are two types of section: a config section specifies general configuration information for IPsec, while a conn section specifies an IPsec connection.

CONN SECTIONS

A conn section contains a connection specification, defining a network connection to be made using IPsec. The name given is arbitrary, and is used to identify the connection to ipsec_auto(8) and ipsec_manual(8). Here`s a simple example:

conn snt left=10.11.11.1 leftsubnet=10.0.1.0/24 leftnexthop=172.16.55.66 right=192.168.22.1 rightsubnet=10.0.2.0/24 rightnexthop=172.16.88.99 keyingtries=%forever

A note on terminology... In automatic keying, there are two kinds of communications going on: transmission of user IP packets, and gateway-to-gateway negotiations for keying, rekeying, and general control. The data path (a set of ``IPsec SAs``) used for user packets is herein referred to as the ``connection``; the path used for negotiations (built with ``ISAKMP SAs``) is referred to as the ``keying channel``.

To avoid trivial editing of the configuration file to suit it to each system involved in a connection, connection specifications are written in terms of left and right participants, rather than in terms of local and remote. Which participant is considered left or right is arbitrary; IPsec figures out which one it is being run on based on internal information. This permits using identical connection specifications on both ends. There are cases where there is no symmetry; a good convention is to use left for the local side and right for the remote side (the first letters are a good mnemonic).

Many of the parameters relate to one participant or the other; only the ones for left are listed here, but every parameter whose name begins with left has a right counterpart, whose description is the same but with left and right reversed.

Parameters are optional unless marked ``(required)``; a parameter required for manual keying need not be included for a connection which will use only automatic keying, and vice versa.

CONN PARAMETERS: GENERAL

The following parameters are relevant to both automatic and manual keying. Unless otherwise noted, for a connection to work, in general it is necessary for the two ends to agree exactly on the values of these parameters.

type: the type of the connection; currently the accepted values are tunnel (the default) signifying a host-to-host, host-to-subnet, or subnet-to-subnet tunnel; transport, signifying host-to-host transport mode; passthrough, signifying that no IPsec processing should be done at all; drop, signifying that packets should be discarded; and reject, signifying that packets should be discarded and a diagnostic ICMP returned.
left: (required) the IP address of the left participant`s public-network interface, in any form accepted by ipsec_ttoaddr(3) or one of several magic values. If it is %defaultroute, and the config setup section`s, interfaces specification contains %defaultroute, left will be filled in automatically with the local address of the default-route interface (as determined at IPsec startup time); this also overrides any value supplied for leftnexthop. (Either left or right may be %defaultroute, but not both.) The value %any signifies an address to be filled in (by automatic keying) during negotiation. The value %opportunistic signifies that both left and leftnexthop are to be filled in (by automatic keying) from DNS data for left`s client. The values %group and %opportunisticgroup makes this a policy group conn: one that will be instantiated into a regular or opportunistic conn for each CIDR block listed in the policy group file with the same name as the conn.
leftsubnet: private subnet behind the left participant, expressed as network/netmask (actually, any form acceptable to ipsec_ttosubnet(3)); if omitted, essentially assumed to be left/32, signifying that the left end of the connection goes to the left participant only
leftnexthop: next-hop gateway IP address for the left participant`s connection to the public network; defaults to %direct (meaning right). If the value is to be overridden by the left=%defaultroute method (see above), an explicit value must not be given. If that method is not being used, but leftnexthop is %defaultroute, and interfaces=%defaultroute is used in the config setup section, the next-hop gateway address of the default-route interface will be used. The magic value %direct signifies a value to be filled in (by automatic keying) with the peer`s address. Relevant only locally, other end need not agree on it.
leftupdown: what ``updown`` script to run to adjust routing and/or firewalling when the status of the connection changes (default ipsec _updown). May include positional parameters separated by white space (although this requires enclosing the whole string in quotes); including shell metacharacters is unwise. See ipsec_pluto(8) for details. Relevant only locally, other end need not agree on it.
leftfirewall: whether the left participant is doing forwarding-firewalling (including masquerading) for traffic from leftsubnet, which should be turned off (for traffic to the other subnet) once the connection is established; acceptable values are yes and (the default) no. May not be used in the same connection description with leftupdown. Implemented as a parameter to the default updown script. See notes below. Relevant only locally, other end need not agree on it.

If one or both security gateways are doing forwarding firewalling (possibly including masquerading), and this is specified using the firewall parameters, tunnels established with IPsec are exempted from it so that packets can flow unchanged through the tunnels. (This means that all subnets connected in this manner must have distinct, non-overlapping subnet address blocks.) This is done by the default updown script (see ipsec_pluto(8)).

The implementation of this makes certain assumptions about firewall setup, notably the use of the old ipfwadm interface to the firewall. In situations calling for more control, it may be preferable for the user to supply his own updown script, which makes the appropriate adjustments for his system.

CONN PARAMETERS: AUTOMATIC KEYING

The following parameters are relevant only to automatic keying, and are ignored in manual keying. Unless otherwise noted, for a connection to work, in general it is necessary for the two ends to agree exactly on the values of these parameters.

keyexchange: method of key exchange; the default and currently the only accepted value is ike
auto: what operation, if any, should be done automatically at IPsec startup; currently-accepted values are add (signifying an ipsec auto --add), route (signifying that plus an ipsec auto --route), start (signifying that plus an ipsec auto --up), manual (signifying an ipsec manual --up), and ignore (also the default) (signifying no automatic startup operation). See the config setup discussion below. Relevant only locally, other end need not agree on it (but in general, for an intended-to-be-permanent connection, both ends should use auto=start to ensure that any reboot causes immediate renegotiation).
auth: whether authentication should be done as part of ESP encryption, or separately using the AH protocol; acceptable values are esp (the default) and ah.
authby: how the two security gateways should authenticate each other; acceptable values are secret for shared secrets, rsasig for RSA digital signatures (the default), secret|rsasig for either, and never if negotiation is never to be attempted or accepted (useful for shunt-only conns). Digital signatures are superior in every way to shared secrets.
leftid: how the left participant should be identified for authentication; defaults to left. Can be an IP address (in any ipsec_ttoaddr(3) syntax) or a fully-qualified domain name preceded by @ (which is used as a literal string and not resolved). The magic value %myid stands for the current setting of myid. This is set in config setup or by ipsec_whack(8)), or, if not set, it is the IP address in %defaultroute (if that is supported by a TXT record in its reverse domain), or otherwise it is the system`s hostname (if that is supported by a TXT record in its forward domain), or otherwise it is undefined.
leftrsasigkey: the left participant`s public key for RSA signature authentication, in RFC 2537 format using ipsec_ttodata(3) encoding. The magic value %none means the same as not specifying a value (useful to override a default). The value %dnsondemand (the default) means the key is to be fetched from DNS at the time it is needed. The value %dnsonload means the key is to be fetched from DNS at the time the connection description is read from ipsec.conf; currently this will be treated as %none if right=%any or right=%opportunistic. The value %dns is currently treated as %dnsonload but will change to %dnsondemand in the future. The identity used for the left participant must be a specific host, not %any or another magic value. The value %cert will load the information required from a certificate defined in %leftcert and automatically define leftid for you. Caution: if two connection descriptions specify different public keys for the same leftid, confusion and madness will ensue.
leftrsasigkey2: if present, a second public key. Either key can authenticate the signature, allowing for key rollover.
leftcert: If you are using leftrsasigkey=%cert this defines the certificate you would like to use. It should point to a X.509 encoded certificate file. If you do not specify a full pathname, by default it will look in /etc/ipsec.d/certs.
leftsendcert: This option configures when Openswan will send X.509 certificates to the remote host. Acceptable values are yes|always (signifying that we should always send a certificate), ifasked (signifying that we should send a certificate if the remote end asks for it), and no|never (signifying that we will never send a X.509 certificate). The default for this option is ifasked which may break compatibility with other vendor`s IPSec implementations, such as Cisco and SafeNet. If you find that you are getting errors about no ID/Key found, you likely need to set this to always.
xauth: Use XAUTH / Mode Config for this connection

OpenSource Headlines

Fast Easy Web Hosting

Your Say About Movies

Cigars Review

Man Pages

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

NAME

DESCRIPTION

ACL TYPES

ACL ENTRIES

VALID ACLs A valid ACL contains exactly one entry with each of the ACL_USER_OBJ,

CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS

OBJECT CREATION AND DEFAULT ACLs The access ACL of a file object is initialized when the object is

ACCESS CHECK ALGORITHM

ACL TEXT FORMS

LONG TEXT FORM

SHORT TEXT FORM

RATIONALE

CHANGES TO THE FILE UTILITIES

STANDARDS

SEE ALSO

POSIX 1003.1e DRAFT 17

POSIX 1003.1e FUNCTIONS BY CATEGORY

POSIX 1003.1e FUNCTIONS BY AVAILABILITY

LINUX EXTENSIONS

NAME

DESCRIPTION

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

BUGS

HISTORY

NAME

DESCRIPTION

SEE ALSO

AUTHOR

NAME

SYNTAX

DESCRIPTION

Program Transfer

EXAMPLE

SEE ALSO

NAME

DESCRIPTION

SEE ALSO

NAME

DESCRIPTION

SEE ALSO

NAME

DESCRIPTION

FORMAT

key

options

location

EXAMPLE

FEATURES

Map Key Substitution

Wildcard Key

Variable Substitution

Executable Maps

Multiple Mounts

Replicated Server

UNSUPPORTED

CAVEATS

SEE ALSO

AUTHOR

NAME

DESCRIPTION

HISTORY

SEE ALSO

NAME

DESCRIPTION

SYNTAX

SYMBOLIC NAMES

CHARACTER ENCODING