mathopd.conf

package: mathopd

title: mathopd.conf(5)

text:
# mathopd.conf(5)

## NAME
This manpage describes the syntax and options of the configuration file of mathopd. Its usual location is /etc/mathopd.conf.

## DESCRIPTION
A configuration file for mathopd consists of zero or more 'items', possibly mixed with comment text.

An item is a configuration keyword followed by zero or one arguments, as indicated by the syntax below.

I have taken the liberty of introducing some meta-concepts to make the syntax more readable.

When you read the phrase "X-block", please replace it with the following.

X-block: "{" X-items "}"

X-items:

<nothing>

X-item X-items

Keywords and arguments are separated by whitespace, that is, spaces, tab characters, carriage returns, or line feeds.

A string is anything enclosed in double quotes ("). The quotes can be omitted if the string is actually just a single word. To include the double quote character itself in a string, precede the quote with a backslash ('´).

An integer is represented using the normal 'C' conventions: '0x' in front indicates a hexadecimal number, '0' in front indicates octal.

The '#' character, when not used inside a string, is considered the beginning of comment text. A comment lasts until the next line. Comments are ignored when the input file is parsed.

## OPTIONS
AcceptMulti

• Where: Tuning

• Type: Flag

• Default: On By default, Mathopd will try to accept more connections after it has accepted one, until the accept call indicates a blocking condition. When there is hardly any traffic, this means that an extra system call is made each time a connection comes in. If you don't want that behaviour, use this keyword to turn it off.

Access

• Where: Control

• Type: Block

• Default: Inherits from previous Access blocks The Access block can be used to allow or deny access to specific IP addresses. Mathopd has a default-allow policy, so if you have no Access blocks, access is allowed to anyone. If you do have Access blocks, make sure that you put the access entries in the correct order. Mathopd scans access blocks from the bottom up until a match is found. Example:

Control {

Access {

Deny 0/0

Allow 127.0.0.1/32

}

}

This will allow access to 127.0.0.1, while denying access to anyone else.

Address

• Where: Server

• Type: Address

• Default: 0 (any address) If you want a server to listen on a specific address, rather than any address, use this keyword. Example:

Server {

Address 127.0.0.1

}

Admin

• Where: Control

• Type: String

• Default: (none) The value of this keyword, if set, is displayed in HTTP error messages.

Alias

• Where: Control

• Type: String Control blocks that contain an Alias keyword are used in URI-to-path translation. A block with an Alias keyword must have one or more Location keywords as well. Generally speaking, Mathopd scans Control blocks until it can match the directory part of the Request-URI with the alias. Scanning starts in the Virtual server and continues upwards. Scanning stops as soon as a match is found.

Example:

Control {

Alias /

Location /usr/share/doc/handbook

}

Control {

Alias /boland

Location /usr/home/boland/www

}

The above is an example of two aliases. Note that the order of the aliases matters: if you switch the two around, unexpected things will happen (the more specific alias will be obscured by the '/' alias.)

Allow

• Where: Access

• Type: Network

AllowDotfiles

• Where: Control

• Type: Flag

• Default: Off Normally, Mathopd will not serve any file if any part of its pathname contains '/.', for security reasons. If the AllowDotFiles flag is set, there restrictions are lifted a bit, although constructions like '/./', '/../', etc. are still disallowed.

AnyHost

• Where: Virtual If a virtual server has this keyword, it will match on any Host: header that is sent by the client. Other virtual servers that have an explicit Host name are still checked, so the 'AnyHost' virtual server will only be used as a last resort. See also the discussion of wildcard expansion under the 'Location' keyword.

Apply

• Where: Clients

• Type: Network

AutoIndexCommand

• Where: Control If a request for a directory is made, and none of the files specified by IndexNames is found in that directory, mathopd will, as a last resort, run a special CGI script to generate a directory listing. The AutoIndexCommand determines which script exactly. The script must be an absolute pathname.

Backlog

• Where: Server

• Type: Integer

• Default: 128 If all connections are in use, and there are no idle connections, Mathopd will make no attempt to accept new connections. The operating system may hold on to new connections though, in which case they will be picked up by Mathopd as soon as one connection becomes idle. The number of connections that can 'hang in the air' in this fashion is determined by the Backlog parameter. Normally one should never have to change this number.

BufSize

• Where: Tuning

• Type: Integer

• Default: 12288 The server uses two buffers to store incoming and outgoing data. The size of the outgoing buffer is determined by the value of the BufSize keyword. Larger buffers can lead to less system calls, but also increase the amount of memory used by the server process.

Note: if you run a version of Mathopd that uses sendfile(), the default bufsize is way too large, and you should decrease it.

BytesRead

• Where: LogFormat The number of octets (bytes) read from the client during a single request.

BytesWritten

• Where: LogFormat The number of octets (bytes) sent to the client during a single request. Note that this number may not be accurate in all cases. If a network error occurs after a successful send operation, the logged number of bytes sent will be too big.

ChildLog

• Where: Control

• Type: String If a child process, such as a CGI script, writes a message to its standard error file descriptor (fd 2) it will end up in the file designated by the ChildLog keyword. If no ChildLog is specified, diagnostic messages will be thrown away.

Clients

• Where: Control

• Type: Block This directive is similar to 'Access', except that it causes combination with Control blocks that contain an Alias. To distinguish a 'Clients' access list from a 'normal' access list, the keywords to be used inside the list are 'Apply' and 'NoApply', rather than

All this is perhaps best illustrated by an example.

Control {

Alias /

Location /usr/share/doc/handbook

}

Control {

Alias /

Location /usr/share/doc/internal/handbook

Clients {

Apply 192.168.57.0/24

}

}

In this example, visitors from within the 192.168.57.0/24 network will get their content served from /usr/share/doc/internal/handbook, whereas other clients will see /usr/share/doc/handbook. Note that the order of the control blocks matters. If you put the unconditional alias at the bottom, rather than at the top, it will be matched first by the server, thus occluding the conditional alias.

Clobber

• Where: Tuning

• Type: Flag

• Default: On Normally, Mathopd closes connections that are idle when a new connection arrives and the maximum number of connections has been reached. This behaviour is called 'clobbering'. By setting the existing connection terminates by itself or times out.

ContentLength

• Where: LogFormat The total size of the resource requested by the client.

Control

• Where: Global, Server, Virtual

• Type: Block The 'Control' keyword starts a so-called control block. As the name suggests, it controls the behaviour of the server. In fact the keyword itself does not do very much; the directives inside the control block do all the work.

Unless the block contains an Alias directive, settings that are specified inside a control block are inherited by all next blocks that are on an equal or lower level.

Control blocks can appear at three different levels. Control bocks that appear at the 'top' level in the configuration file are called global control blocks. Next, one can put control blocks inside Server blocks. The settings defined there are local to that specific server. And finally one can have control blocks inside Virtual blocks. These blocks are on the lowest level.

Usually a configuration file is made up of one very large global control block, followed by a bunch of Virtual servers that each contain a small control block, mostly containing just an Alias and a Location directive.

CoreDirectory

• Where: Global

• Type: String Normally, for practical reasons, the server changes its current directory to the root directory "/". If this is undesirable for whatever reason, you can specify an alternate directory here. As a side effect, if mathopd dumps core for whatever reason, the core file will be in this directory. Actually if the server is started by root it will never dump core for security reasons, so this feature is a bit useless.

Ctime

• Where: LogFormat The current time in 'C' format (e.g. Sun Mar 30 21:44:52 2003.)

Deny

• Where: Access

• Type: Network

EncryptedUserFile

• Where: Control

• Type: Flag

• Default: Off Normally, the UserFile (see the descriptions of the Realm and Userfile keywords) contains passwords in clear-text format. If you want to use encrypted passwords (for example, using the to 'On' in the control block that contains the UserFile in question.

Error401File

• Where: Control

• Type: String The contents of this file will be displayed whenever a '401' (not authorized) error occurs. The file may be a CGI script or an external command. If CGI scripts are used, the script is responsible for sending the proper status code.

Error403File

• Where: Control

• Type: String The contents of this file will be displayed whenever a '403' (forbidden) error occurs. For more information, see Error401File.

Error404File

• Where: Control

• Type: String The contents of this file will be displayed whenever a '404' (not found) error occurs. For more information, see Error401File.

ErrorLog

• Where: Global

• Type: String The server process will print diagnostics messages into this file. Mathopd will open the error log in write-only mode. If it does not have permission to do that, the program will exit. Note that if the value of ErrorLog contains a percent sign (%), the name of the error logfile will be expanded using a strftime-like contruction (see also: Log.)

ExactMatch

• Where: Control

• Type: Flag The ExactMatch causes an Alias to be used only if it matches the request-URI exactly. This is rather a hack. It was originally designed to disallow users more than one html page per web site. The way this is done is as follows

Control {

IndexNames { index.html }

Types {

text/html { html htm }

}

}

Server {

Virtual {

Host www.another.example

Control {

Alias /

Location /var/www/www.another.example

Specials {

Dummy { html htm }

}

}

Control {

Alias /

Location /var/www/www.another.example

ExactMatch On

}

}

\# other virtual servers ...

}

Now if someone requests http://www.another.example/, the alias will match exactly, so the control block at the bottom will be in effect. On the other hand, if a request is made for, say, http://www.another.example/foo.html, the alias will not match exactly, so the second control block from the bottom will be used. This control block overrides the type declaration for html and htm extensions, effectively hiding these files, even if they were to exist physically. Note that files with extensions other than html and htm are processed normally, so that you can for example still have things like images on your home page.

Export

• Where: Control

• Type: Block Some operating systems require that some environment variables have certain values in order for child processes to work correctly. To export these variables to child processes, use the 'Export' keyword. If you want to export certain variables with preset values, use 'PutEnv' instead. Example:

Control {

Export { TZ LD_LIBRARY_PATH }

}

External

• Where: Control

• Type: Block The 'External' keywords defines a set of filename extensions that get special treatment. (See also: Types, Specials.) If mathopd processes a filename whose extension is match in an 'External' block, it will run an external program with the name of the file as its first argument. Before execution, mathopd will change its current directory to the directory that contains the file that is being served. Example:

Control {

External {

/usr/bin/perl { .pl }

}

}

This will treat all files that end with '.pl' as CGI scripts, interpreted by /usr/bin/perl.

It is possible to pass additional arguments to interpreters. For example, if you want to run all perl scripts with the '-T' option, use the following construction:

Control {

External {

"/usr/bin/perl -T" { .pl }

}

}

ExtraHeaders

• Where: Control

• Type: Block Use this keyword to add extra HTTP headers. This is perhaps best demonstrated by an example.

Control {

ExtraHeaders { "Cache-Control: max-age=3600" }

}

If this is done, all responses, well, to be precise, all responses with status code 200, will be accompanied by a

Cache-Control: max-age=3600

HTTP header.

Host

• Where: Virtual

• Type: String A virtual server has zero or more names. To name a virtual server, use the 'Host' keyword. More than one `Host' keyword is allowed for each virtual server.

IndexNames

• Where: Control

• Type: Block Any request that ends with a slash ('/') is treated as an `index'. The terminology is a bit confusing, since no indexes are actually being made. What happens is that mathopd will map the request-URI to a directory. This directory is then scanned for a set of files called indexes. (For instance 'index.html'). As soon as a file is found, that file will be sent to the client. Example:

Control {

IndexNames { index.html Default.htm }

}

Note that the value of 'IndexNames' is carried over into all subsequent control blocks. That is, if you define IndexNames once it is not possible to reset its value later on.

InputBufSize

• Where: Tuning

• Type: Integer

• Default: 2048 The input buffer contains the complete set of headers sent by the client. As such, it needs to be large enough to contain all those headers. Usually the default value of 2048 is sufficient and does not need to be changed.

LocalAddress

• Where: LogFormat The local Internet address of the connection.

LocalPort

• Where: LogFormat The port number of the server.

Location

• Where: Control

• Type: String The Location keyword is used in combination with the Alias keyword. There are two types of locations: physical locations and 'redirects'. A physicial location is anything that starts with a slash ('/'), a redirect is anything else. When mathopd processes a request, the Alias that matches the Request-URI sent by the client is replaced with its corresponding location. For example, in the following situation

Control {

Alias /doc

Location /usr/share/doc/handbook

}

when a client requests a URI '/doc/x11.html', the server will send the contents of /usr/share/doc/handbook/x11.html. When the location is a redirect, the server will send a HTTP to the desired location. Example:

Control {

Alias /secure

Location https://an.example

}

In this example, when a client request a URI '/secure/test.html', the server will redirect the client to 'https://an.example/test.html'.

More than one Location keywords can be used with one alias. Mathopd will rotate the locations on a round-robin bases. Example:

Control {

Alias /download

Location http://mirror1.an.example/download

Location http://mirror2.an.example/download

Location http://mirror3.an.example/download

}

The first client that request something under /download will be redirected to mirrior1.an.example, the second client to mirror2, the third to mirror3, the fourth to mirror1, and so on.

Wildcard expansion: the wildcard character '*' in Location values is expanded to the current value of the 'host' header sent by the client (after conversion to lower case.) This makes it possible to define a very large number of virtual servers in one go. Example:

Server {

Virtual {

AnyHost

Control {

Alias /

Location /home/www/*

}

}

}

With this setting, a request for, say, http://an.example/foo.html will result in the file /home/www/an.example/foo.html.

Log

• Where: Global

• Type: String This keyword determines where the access log is stored. The server creates one and only one access log, regardless of the number of (virtual) servers. The log file must be writeable by the user the server runs as. If no log file exists, Mathopd will try to create one. In that case, the server must also have write access to the directory that will contain the log file. There are some hacks that make it easier to maintain logs for distinct time periods. Before Mathopd tries to open the log file, it will expand any '%' constructs in the log file name, similar to date(1) and strftime(3). For example, if

Log /var/mathopd/log.%Y%m%d

is used, Mathopd will expand the %Y, %m and %d in the file name, to something like /var/mathopd/log.20020831 Mathopd automatically rotates the log file every hour. If during this process Mathopd cannot create a new log file for any reason, it will continue to append to the old log. The format of the access log is determined by whatever is specified in the LogFormat block (see below.)

LogFormat

• Where: Global

• Type: Block This keyword determines the order in which items are written into the log file. Each line of the log file consists of some tab- separated fields. The contents of each field is determined by whatever is inside the LogFormat block. For example, if the following is specified

LogFormat { CTime URI }

the first field in the log file corresponds to the date and time of the request, and the second field corresponds to the client's request-URI at that time.

The default field order for the log is as follows.

Ctime

RemoteUser

RemoteAddress

RemotePort

ServerName

Method

Uri

Status

ContentLength

Referer

UserAgent

BytesRead

BytesWritten

In addition to the above, the following fields are available:-

LocalAddress

LocalPort

Version

QueryString

TimeTaken

MicroTime

LogGMT

• Where: Global

• Type: Flag

• Default: Off Normally time stamps in log files are in local time. If LogGMT is set to 'On', time stamps are in GMT. Note that this setting also affects naming of log files when

Method

• Where: LogFormat The client's request-method, usually GET.

MicroTime

• Where: LogFormat The time, measured in seconds, with microsecond precision, since 00:00:00 UTC, January 1, 1970. (Or whatever is returned by the gettimeofday() system call.)

NoApply

• Where: Clients

• Type: Network

NoHost

• Where: Virtual A Virtual server that has the "NoHost" keyword will be used when no Host header is sent by the client.

NumConnections

• Where: Tuning

• Type: Integer

• Default: 64 The NumConnections parameter determines how many simultaneous requests can be handled. The default is probably too low for high-traffic systems. Mathopd uses a fixed block of memory for each connection, so the higher you set this tunable, the more memory the server will use.

See also: Clobber.

Note: the amount of memory that is used by Mathopd for buffers can be approximated by the formula

Memory =

NumConnections * (BufSize + InputBufSize + 2 * ScriptBufSize)

NumHeaders

• Where: Tuning

• Type: Integer

• Default: 100 This keyword has a dual purpose.

Mathopd keeps track of the HTTP headers that are sent by a client to pass on to child processes. Since each of these headers must be stored somewhere, a fixed amount of memory is set aside for these. The number of HTTP headers that are actually stored is determined by the value of NumHeaders. If a client sends more headers these will still be processed by the server, but they will not be available as environment variables.

This keyword has an additional function: it determines the maximum number of headers that a CGI script can send. It is an error for a script to send more than this number of headers.

PIDFile

• Where: Global

• Type: String The PIDFile keyword specifies a file in which the server will record its process ID, for tracking purposes.

PathArgs

• Where: Control

• Type: Flag If you want to redirect a user to a different web site, regardless of the actual URL that is requested, you can do something like this

Control {

Alias /foo

Location http://www.an.example/foo.html

PathArgs On

}

In the above example, a request for, say, /foo/index.html will be redirected to http://www.an.example/foo.html. In fact, *any* request that starts with /foo/ will be redirected to the same URL. If the PathArgs were omitted a request for /foo/index.html would be redirected to http://www.an.example/foo.html/index.html (which does not make much sense of course.)

The PathArgs keyword was originally created to solve a problem related to hit metering. If you have a website, but no control over its logfiles, you can create hidden images on your site that link to a statistics gathering site. This is a well-known process of course. If the statistics-gathering runs mathopd it can be set up something like this:-

Control {

Alias /

Location /usr/local/www/tiny-image.png

PathArgs On

}

This way, every request will return the same response, namely, the contents of tiny-image.png. If the two websites cooperate, the request-URI that appears in the log file on the gathering website can then be used to collect hit-metering data for the original site.

PathInfo

• Where: Control

• Type: Flag

• Default: On Normally mathopd allows requests for things like /script.cgi/args, where /args is passed as 'path info' to the script.cgi program. This works by mathopd chopping off all trailing path components until a file is found. This operation can be quite expensive and in most circumstances it is not needed. Worse yet, a request for, say, /a/b/c/d/e/f/g/h will result in eight system calls.

To turn the 'chopping' behaviour off, set the value of PathInfo to Off.

Note that PathInfo defaults to On for backwards compatibility.

Port

• Where: Server

• Type: Integer

• Default: 80 If you want Mathopd to run a server on a different port, rather than the default for http, which is port 80, use a Port declaration. Example:

Server {

Port 8080

}

PutEnv

• Where: Control

• Type: Block This is like Export, except that environment variables defined here must accompanied by a value. Example: (rather silly)

Control {

PutEnv {

MATHOPD_INVOKED=1

}

}

There must be no space between the name of an environment variable, the equals sign, and its value. If the value contains space characters the entire name=value bit must be enclosed in double quotes.

QueryString

• Where: LogFormat The query string (the part that follows the '?' in the request-URI) if present.

Realm

• Where: Control

• Type: String If this keyword is present in a control block, resources in that block are protected using username-password combinations. The Realm keyword must be accompanied by a UserFile keyword. The value of the Realm keyword is transmitted to the client in '401' error responses. Its value may be displayed by a web browser in a login dialog.

Referer

• Where: LogFormat The value of the 'Referer:' header sent by the client. Sometimes this refers to a URL that contains a link to the current request.

RemoteAddress

• Where: LogFormat The Internet Address of the client.

RemotePort

• Where: LogFormat The port number at the client's end of its connection to the server.

RemoteUser

• Where: LogFormat The username sent by the client for a request that needs authorization and has successfully authenticated.

RootDirectory

• Where: Global

• Type: String If this keyword is present, mathopd will perform a chroot() to the specified directory before startup. The chroot() is done right after the configuration file is read. Obviously the server must be started as root for this to work. Some additional files may be required in the new root, like a (stripped down) /etc/passwd and so on.

RunScriptsAsOwner

• Where: Control

• Type: Flag

• Default: Off Normally, if the server is started as root and the StayRoot flag is set, child processes are run as a certain user (see the StayRoot and ScriptUser keywords.) It is possible to run CGI scripts as the user that owns them by setting the RunScriptsAsOwner flag. This is not recommended, since it is possible to trick mathopd using symbolic links.

ScriptBufSize

• Where: Tuning

• Type: Integer

• Default: 4096 The server uses two buffers for CGI scripts: one for data that is passed to a script, and another for data arriving from a script. It is recommended that ScriptBufSize be equal to or greater than InputBufSize. Also the ScriptBufSize should be at least sixteen bytes less than BufSize, to leave room in the output buffer for "chunk" delimiters.

ScriptTimeout

• Where: Tuning

• Type: Integer

• Default: 60 This timeout determines how long, measured in seconds, scripts can run without generating any output.

ScriptUser

• Where: Control

• Type: String If a CGI or external program is executed, Mathopd will change its identity to make sure that such programs cannot do silly things like kill the web server process and so on. The recommended way to set the user for child processes is with the ScriptUser keyword. Its argument is a user name that will be looked up in the system password file right before execution of each program. See also: StayRoot.

Server

• Where: Global

• Type: Block The Server keyword sets up a physical server, that is, a TCP socket. Some TCP parameters may be tuned (see Address and Port.) Inside a server block one can then declare 'virtual' servers, which is where all action occurs.

ServerName

• Where: LogFormat The value of the 'Host:' header sent by the client (more or less.)

Specials

• Where: Control

• Type: Block Some file extensions can be treated specially if they are put into a 'Specials' block. There are four specialties:

CGI

Imagemap

Redirect

Dump

If a specialty is defined with a name that is not one of the above four, a file that matches that specialty is treated as if it did not exist. (See the 'Dummy' example in the description of the ExactMatch keyword.)

A very brief description of the four specialties follows.

For a description of CGI, see cgi.txt. An imagemap is a fairly ancient concept. It is generally not used anymore but it is kept around for historical reasons. A redirect file simply redirects the client to a URL that is contained in the file. A Dump displays some mildly interesting server statistics but is otherwise not very useful.

Example:

Control {

Specials {

CGI { cgi }

Imagemap { map }

}

}

Status

• Where: LogFormat The three-digit HTTP status code for this request.

StayRoot

• Where: Global

• Type: Flag

• Default: Off Mathopd, if it is started by root, will change its identity to that of a nonprivileged user (see the User keyword.) It is sometimes desirable to retain some root privileges, for example when external processes are started. One does not really want those child processes to be able to interfere with the server process itself, therefore these processes must be run under a different identity. In order to accomplish this, set the StayRoot flag.

Timeout

• Where: Tuning

• Type: Integer

• Default: 60 Connections that are idle for too long are aborted by Mathopd. Idle in this case meaning 'receiving or transmitting no data.' It is possible to increase or decrease the timeout by adding a Timeout keyword. The unit of the timeout value is seconds.

See also: ScriptTimeout and Wait.

TimeTaken

• Where: LogFormat The time it has taken for the request to complete. Time is measured from the first meaningful byte received from the client, or the time the client connected.

Tuning

• Where: Global

• Type: Block Some items that control general tuning of the server can be specified here.

Types

• Where: Control

• Type: Block All served content must be accompanied by a 'Content-Type' header that indicates the kind of content. Historically, HTTP servers have used the extension of a filename to determine its content. For example a file whose name ends with 'html' is likely to contain HTML, a file with a name ending with 'png' is probably a PNG image, and so on. Mathopd follows this behaviour. File extensions are mapped to media types (values of 'Content-Type' that web browsers understand) using the 'Types' keyword. Example:

Control {

Types {

text/html { html htm }

text/plain { txt }

image/jpeg { jpg }

application/octet-stream { * }

}

}

As you can see, the media type is followed by a group of extensions that will be mapped to that type. The special extension '*' is used to indicate a default: if a filename has an extension that does not occur in any of the Types (or Specials or External), then the type for '*' (if it is defined) is used.

Note that for Mathopd, 'extension' really means just `last part'. For example, a file that is called 'flubrdhtml' is deemed to be a HTML file even though it does not really have an extension. This is a bit of a misfeature, but it does no real harm in practice.

Umask

• Where: Global

• Type: Integer

• Default: 022 Mathopd will create log files with certain permissions. These permissions are determined by what is called in Unix lingo the readable by everyone but writeable only by the user that runs the server process. More restricted umasks are 026 or even 066. (The 0 at the beginning is not optional!)

Note: the umask is inherited by child processes.

Uri

• Where: LogFormat The URI requested by the client (minus query string, if present.)

User

• Where: Global

• Type: String If Mathopd is started by root it must change its identity. This is done for security reasons: you do not want the web server to be able to read all files. The new identity is defined by the value of the User keyword. The user name is looked up in the password file (this is done before a possible chroot!) and Mathopd then changes its effective user id (and real user id as well, depending on whether StayRoot is off or on). In addition, Mathopd will perform a setgroups() call to clear its list of supplementary group ids.

Note: Mathopd will create log files, etc. with an owner that is equal to the value of the User keyword. The *group* owner of the log file may differ between operating systems. For example, on BSD, the group owner of a file is set to the group owner of the directory in which it is created. Other systems may have different semantics.

UserAgent

• Where: LogFormat The value of the 'User-Agent:' header sent by the client. This may, or may not, contain a string that can identify a web browser.

UserDirectory

• Where: Control

• Type: Flag To allow each user to put up his or her personal pages, use the UserDirectory kyeword. Example:

Control {

Alias /users

Location public_html

UserDirectory On

}

In this example, a request for /users/boland/index.html will result in a password lookup for user 'boland'. Assume the home directory for this user is /home/boland. Then the file served will be /home/boland/public_html/index.html.

Note: the '~' character, when used as the last character in an alias is treated specially. For example:

Control {

Alias /~

Location public_html

UserDirectory On

}

With this setting, /~boland/index.html will be mapped to /home/boland/public_html/index.html, like before. This is to allow some sort of compatibilty to the often used custom to use

UserFile

• Where: Control

• Type: String Control blocks that are 'protected' by a Realm keyword need a UserFile keyword as well. The user file contains all username / password combinations that are valid for that specific realm. The user file should contain lines that look like

username:password

(with username and password replaced by a real username and password of course.) A user can be entered more than once with different passwords. The user file has no relation whatsoever to the system password file. Passwords can be encrypted, but Mathopd needs to be told that they are encrypted, using the EncryptedUserFile keyword.

Version

• Where: LogFormat The HTTP version requested by the client.

Virtual

• Where: Server, Global

• Type: Block The 'Virtual' keyword starts a virtual server block. Virtual blocks can be declared globally or inside a server block. Global virtual blocks are inherited by all servers that follow.

Wait

• Where: Tuning

• Type: Integer

• Default: 60 The value of 'Wait' represents the amount of time, in seconds, the server will wait for a request from the client.

## AUTHOR
Mathopd was written and is copyright by Michiel Boland.

## SEE ALSO
mathopd (8)


mcxio

package: mcl

title: mcxio(5)

text:
# mcxio(5)

## NAME

mcxio - the format specifications for input and output in the mcl family.

## DESCRIPTION

This document describes

native matrix format

The format that can be read in by any mcl application expecting a matrix argument. The native format closely resembles the layout of matrices as residing in computer memory. There are two distinct encodings, respectively interchange and binary. Their relative merits are described further below.

concatenated native matrix format

This always pertains to matrices in native format concatenated in a single file, refered to as a cat file. It is used for example to encode hierarchical clusterings as generated by mclcm. A cat file either consists of matrices in interchange format or of matrices in binary format.

raw intermediate format

This is read by mcxassemble(1).

tab format

Used by applications such as mcl(1) and mcxdump(1) to convert between meaningful labels describing the input data and the numerical identifiers used internally.

label format

The format used when streaming labels directly into mcl(1) or mcxload(1).

transformation syntax

The syntax accepted by mcl(1), mcxload(1), mcxsubs(1) and mcxassemble(1) to transform values in an input stream or in input or output matrices.

The interchange format is a portable format that can be transmitted across computers and over networks and will work with any version of mcl or its sibling programs. It is documented (here) and very stable. Applications can easily create matrices in this format. The drawback of interchange format is that for very large graphs matrix encodings grow very big and are slow to read.

The binary format is not garantueed to be portable across machines or different versions of mcl or differently compiled versions of mcl. Its distinct advantage is that for very large graphs the speed advantage over interchange format is dramatic.

Conversion between the two formats is easily achieved with mcxconvert(1). Both mcl(1) and mcxload(1) can save a matrix in either format after constructing it from label input.

The concatenated format is generated e.g. by mclcm(1) and can be transformed by mcxdump(1) using the -imx-cat option. In cat format matrices are simply concatenated, so it is easily generated from the command line if needed. For native binary format it is imperative that no additional bytes are inserted inbetween the matrix encodings. For native interchange format the only requirement is that the last matrix is followed by nothing but white space.

A remark on the sloppy naming conventions used for mcl and its sibling utilities may be in order here. The prefix mcx is used for generic matrix functionality, the prefix clm is used for generic cluster functionaliy. The utility mcx is a general purpose interpreter for manipulating matrices (and grahps, sets, and clusterings). The set of all mcl siblings (cf. mclfamily(7)) is loosely refered to as the mcl family, which makes use of the mcl libraries (rather than the mcx libraries). The full truth is even more horrible, as the mcl/mcx prefix conventions used in the C source code follow still other rules.

In this document, 'MCL' means 'the mcl setting' or 'the mcl family'. An MCL program is one of the programs in the mcl family. The remainder of this document contains the following sections.

## Internal representation of matrices in MCL

There are several aspects to the way in which MCL represents matrices. Internally, indices never act as an ofset in an array, and neither do they participate in ofset computations. This means that they purely act as identifiers. The upshot is that matrices can be handled in which the index domains are non-sequential (more below). Thus one can work with different graphs and matrices all using subsets of the same set of indices/identifiers. This aids in combining data sets in different ways and easily comparing the respective results when experimenting. Secondly, only nonzero values (and their corresponding indices) are stored. Thirdly, MCL stores a matrix as a listing of columns. Iterating over a column is trivial; iterating over a row requires a costly transposition computation. The last two points should matter little to the user of MCL programs.

In textbook expositions and in many matrix manipulation implementations, matrices are represented with sequentially indexed rows and columns, with the indices usually starting at either zero or one. In the MCL setting, the requirement of sequentiality is dropped, and it follows naturally that no requirement is posed on the first index. The only requirement MCL poses on the indices is that they be nonnegative, and can be represented by the integer type used by MCL. On many machines, the largest allowable integer will be 2147483647.

MCL associates two domains with a matrix M, the row domain and column domain. The matrix M can only have entries M[i,j] where i is in the row domain and j is in the column domain. This is vital when specifying a matrix: it is illegal to specify an entry M[i,j] violating this condition. However, it is not necessary to specify all entries M[i,j] for all possible combinations of i and j. One needs only specify those entries for which the value is nonzero, and only nonzero values will be stored internally. In the MCL matrix format, the matrix domains must be specified explicitly if they are not canonical (more below).

Strictly as an aside, the domains primarily exist to ensure data integrity. When combining matrices with addition or multiplication (e.g. using the mcx utility), MCL will happily combine matrices for which the domains do not match, although it will usually issue a warning. Conceptually, matrices auto-expand to the dimensions required for the operation. Alternatively, a matrix can be viewed as an infinite quadrant, with the domains delimiting the parts in which nonzero entries may exist. In the future, facilities could be added to MCL (c.q. mcx) to allow for placing strict domain requirements on matrices when submitted to binary operations such as addition and multiplication.

## Specifying matrices

From here on, all statements about matrices and graphs are really statements about matrices and graphs in the MCL setting. The specification of a matrix quite closely matches the internal representation.

A matrix M has two domains: the column domain and the row domain. Both simply take the form of a set (represented as an ordered list) of indices. A canonical domain is a domain of some size K where the indices are simply the first K nonnegative integers 0,1..,K-1. The domains dictate which nonzero entries are allowed to occur in a matrix; only entries M[i,j] are allowed where i is in the row domain and j is in the column domain.

The matrix M is specified in three parts, for which the second is optional. The parts are:

Header specification

This specifies the dimensions K and L of the matrix, where K is the size of the row domain, and L is the size of the column domain. It looks as follows:

```
(mclheader
mcltype matrix
dimensions 9x14
)
```

This dictates that a matrix will be specified for which the row domain has dimension 9 and the column domain has dimension 14.

Domain specification

The domain specification can have various forms: if nothing is specified, the matrix will have canonical domains and a canonical representation, similar to the representation encountered in textbooks. Alternatively, the row and column domains can each be specified separately, and it is also possible to specify only one of them; the other will simply be a canonical domain again. Finally, it is possible to declare the two domains identical and specify them simultaneously. It is perfectly legal in each case to explicitly specify a canonical domain. It is required in each case that the number of indices listed in a domain corresponds with the dimension given in the header.

An example where both a row domain and a column domain are specified:

```
(mclrows

 100 200 300 400 500 600 700 800 900 $
)
(mclcols

 30 32 34 36 38 40 42 44 46 48 50 52 56 58 $
)
```

This example combines with the header given above, as the dimensions fit. Had the row domain specification been omitted, the row domain would automatically be set to the integers 0,1,..8. Had the column specification been omitted, it would be set to 0,1,..13.

Suppose now that the header did specify the dimensions 10x10. Because the dimensions are identical, this raises the possibility that the domains be identical. A valid way to specify the row domain and column domain in one go is this.

```
(mcldoms

 11 22 33 44 55 66 77 88 99 100 $
)
```

Matrix specification

The matrix specification starts with the sequence

```
(mclmatrix
begin
```

The 'begin' keyword in the '(mclmatrix' part is followed by a list of listings, where the primary list ranges over all column indices in M (i.e. indices in the column domain), and where each secondary lists encodes all positive entries in the corresponding column. A secondary list (or matrix column) starts with the index c of the column, and then contains a listing of all row entries in c (these are matrix entries M[r,c] for varying r). The entry M[r,c] is specified either as 'r' or as 'r:f', where f is a float. In the first case, the entry M[r,c] defaults to 1.0, in the second case, it is set to f. The secondary list is closed with the `$' character. A full fledged examples thus looks as follows:

```
(mclheader
mcltype matrix
dimensions 12x3
)
(mclrows

 11 22 33 44 55 66 77 88 99 123 456 2147483647 $
)
(mclcols

  0  1  2 $
)
(mclmatrix
begin
0    44 88 99 456 2147483647 $
1    11 66 77 123 $
2    22 33 55 $
)
```

Note that the column domain is canonical; its specifiation could have been omitted. In this example, no values were specified. See below for more.

## Specifying graphs

A graph is simply a matrix where the row domain is the same as the column domain. Graphs should have positive entries only. Example:

```
(mclheader
mcltype matrix
dimensions 12x12
)
(mcldoms
11 22 33 44 55 66 77 88 99 123 456 2147483647 $
)
(mclmatrix
begin
11    22:2  66:3.4  77:3  123:8 $
22    11:2  33:3.8  55:8.1 $
33    22:3.8  44:7  55:6.2 $
44    33:7  88:5.7  99:7.0 456:3 $
55    22:8.1  33:6.2  77:2.9  88:3.0 $
66    11:3.4  123:5.1 $
77    11:3  55:2.9  123:1.5 $
88    44:5.7  55:3.0  99:3.0 456:4.2 $
99    44:7.0  88:3.0 456:1.8 2147483647:3.9 $
123   11:8  66:5.1  77:1.5 $
456   44:3  88:4.2  99:1.8 2147483647:6.3 $
2147483647   99:3.9 456:6.3 $
)
```

Incidentally, clustering this graph with mcl, using default parameters, yields a cluster that is represented by the 12x3 matrix shown earlier.

The following example shows the same graph, now represented on a canonical domain, and with all values implicitly set to 1.0:

```
(mclheader
mcltype matrix
dimensions 12x12
)
(mclmatrix
begin
0    1  5  6  9 $
1    0  2  4 $
2    1  3  4 $
3    2  7  8 10 $
4    1  2  6  7 $
5    0  9 $
6    0  4  9 $
7    3  4  8 10 $
8    3  7 10 11 $
9    0  5  6 $
10   3  7  8 11 $
11   8 10 $
)
```

Additional notes

There are few restrictions on the format that one might actually expect. Vectors and entries may occur in any order and need not be sorted. Repeated entries and repeated vectors are allowed but are always discarded while an error message is emitted.

If you want functionally interesting behaviour in combining repeated vectors and repeated entries, have a look at the next section and at mcxassemble(1).

Within the vector listing, the '#' is a token that introduces a comment until the end of line.

## Raw format

A file in raw format is simply a listing of vectors without any sectioning structure. No header specification, no domain specification, and no matrix introduction syntax is used - these are supplied to the processing application by other means. The end-of-vector token '$' must still be used, and the comment token '#' is still valid. mcxassemble(1) imports a file in raw format, creates a native matrix from the data therein, and writes the matrix to (a different) file. It allows customizable behaviour in how to combine repeated entries and repeated vectors. This is typically used in the following procedure. A) Do a one-pass-parse on some external cooccurrence file/format, generate raw data during the parse and write it to file (without needing to build a huge data structure in memory). B) mcxassemble takes the raw data and assembles it according to instruction into a native mcl matrix.

## Tab format / label information

Several mcl programs accept options such as -tab, -tabc, -tabr, -use-tab, -strict-tab, and -extend-tab. The argument to these options is invariably the name of a so-called tab file. Tab files are used to convert between labels (describing entities in the data) and indices as used in the mcl matrix format. In a tab file each line starts with a unique number which presumably corresponds to an index used in a matrix file. The rest of the line contains a descriptive string associated with the number. It is required that each string is unique, although not all mcl programs enforce this at the time of writing. The string may contain spaces. Lines starting with # are considered comment and are disregarded.

Tab domain

The ordered set of indices found in the tab file is called the tab domain.

Tab files are almost always employed in conjunction with an mcl matrix file. mcxdump(1) and clmformat(1) require by default that the tab domain coincides with the matrix domain (either row or column or both) to which they will be applied. This can be relaxed for either by supplying the --lazy-tab option.

mcl provides explicit modes for dealing with tab structures by means of the -extend-tab, -restrict-tab and -strict-tab options. Refer to the mcl(1) documentation.

## Label input

Label input is a line based input where two nodes and an optional value are specified on each line. The nodes should be specified by labels. If the labels contain spaces they should be separated by tabs (and the value if present should be separated from the second label by a tab as well). The parse code will assume tab-separated labels if it sees a tab character in the input, otherwise it will split the input on any kind of whitespace. Any line where the first non-whitespace character is the octothorp (#) is ignored. The following is an example of label input.

```
---8<------8<------8<------8<------8<---
# the cat and the hat example
cat hat  0.2
hat bat  0.16
bat cat  1.0
bat bit  0.125
bit fit  0.25
fit hit  0.5
hit bit  0.16
--->8------>8------>8------>8------>8---
```

```

```

mcl(1) can read in label input and cluster it when it is given the --abc option. It can optionally save the input graph in native format and save the label information in a tab file with the -save-graph and -save-tab options.

Refer to the MCL getting started and MCL manual examples sections for more information on how MCL deals with label input.

mcxload(1) is a general purpose program for reading in label data and other stream formats. It encodes them in native mcl format and tab files. It allows intermediate transformations on the values.

## Transformation syntax

mcl(1), mcxload(1), mcxsubs(1), mcxassemble(1) all accept the same transformation language in their respective tf-type options and mcxsub's val specification.

A statement in this language is simply a comma-separated list of functions accepting a single numerical value. The syntax of a function invocation in general is func(arg). The functions exp, log, neglog can also be given an empty parameter list, indicating that e is taken as the exponent base. In this case, the invocation looks like func(). The following functions are supported.

lt Filter out values greater than or equal to arg.

lq Filter out values greater than arg.

gq Filter out values less than arg.

gt Filter out values less than or equal to arg.

ceil Set everything higher than arg to arg.

floor Set everything lower than arg to arg.

mul Multiply by arg.

add Add arg to it.

power Raise to power arg.

exp Raise arg (e if omitted) to value.

log Take log in base arg (e if omitted).

neglog Take minus log in base arg (e if omitted).

NOTE

mcl(1) accepts --abc-log and --abc-neg-log to specify log transformations. Similarly, mcxload(1) accepts --stream-log and --stream-neg-log. The reason is that probabilities are sometimes encoded below the precision dictated by the IEEE (32 bit) float specification. This poses a problem as the mcl applications encode values by default as floats, and the transformation specifications are always applied to the mcl encoding. The options just mentioned are applied after a value has been read from an input stream and before it is converted to the native encoding.

## SEE ALSO

mcxassemble(1), and mclfamily(7) for an overview of all the documentation and the utilities in the mcl family.

## AUTHOR

Stijn van Dongen.

branch: sisyphus


mdadm.conf

package: mdadm-tool

title: mdadm.conf(5)

text:
# mdadm.conf(5)

## NAME
mdadm.conf - configuration for management of Software RAID with mdadm

## SYNOPSIS
/etc/mdadm.conf

## DESCRIPTION
mdadm is a tool for creating, managing, and monitoring RAID devices using the md driver in Linux.

Some common tasks, such as assembling all arrays, can be simplified by describing the devices and arrays in this configuration file.

### SYNTAX
The file should be seen as a collection of words separated by white space (space, tab, or newline). Any word that beings with a hash sign (#) starts a comment and that word together with the remainder of the line is ignored.

Spaces can be included in a word using quotation characters. Either single quotes (') or double quotes (") may be used. All the characters from one quotation character to next identical character are protected and will not be used to separate words to start new quoted strings. To include a single quote it must be between double quotes. To include a double quote it must be between single quotes.

Any line that starts with white space (space or tab) is treated as though it were a continuation of the previous line.

Empty lines are ignored, but otherwise each (non continuation) line must start with a keyword as listed below. The keywords are case insensitive and can be abbreviated to 3 characters.

The keywords are:

DEVICE

A device line lists the devices (whole devices or partitions) that might contain a component of an MD array. When looking for the components of an array, mdadm will scan these devices (or any devices listed on the command line). The device line may contain a number of different devices (separated by spaces) and each device name can contain wild cards as defined by glob(7).

Also, there may be several device lines present in the file.

Alternatively, a device line can contain either or both of the words containers and partitions. The word containers will cause mdadm to look for assembled CONTAINER arrays and included them as a source for assembling further arrays.

The word partitions will cause mdadm to read /proc/partitions and include all devices and partitions found therein. mdadm does not use the names from /proc/partitions but only the major and minor device numbers. It scans /dev to find the name that matches the numbers.

If no DEVICE line is present in any config file, then "DEVICE partitions containers" is assumed.

For example:

DEVICE /dev/hda* /dev/hdc*

DEV /dev/sd*

DEVICE /dev/disk/by-path/pci*

DEVICE partitions

ARRAY

The ARRAY lines identify actual arrays. The second word on the line may be the name of the device where the array is normally assembled, such as /dev/md1 or /dev/md/backup. If the name does not start with a slash ('/'), it is treated as being in /dev/md/. Alternately the word <ignore> (complete with angle brackets) can be given in which case any array which matches the rest of the line will never be automatically assembled. If no device name is given, mdadm will use various heuristics to determine an appropriate name. Subsequent words identify the array, or identify the array as a member of a group. If multiple identities are given, then a component device must match ALL identities to be considered a match. Each identity word has a tag, and equals sign, and some value. The tags are:

uuid=

The value should be a 128 bit uuid in hexadecimal, with punctuation interspersed if desired. This must match the uuid stored in the superblock.

super-minor=

The value is an integer which indicates the minor number that was stored in the superblock when the array was created. When an array is created as /dev/mdX, then the minor number X is stored.

devices=

The value is a comma separated list of device names or device name patterns. Only devices with names which match one entry in the list will be used to assemble the array. Note that the devices listed there must also be listed on a DEVICE line.

level=

The value is a RAID level. This is not normally used to identify an array, but is supported so that the output of mdadm --examine --scan

can be use directly in the configuration file.

num-devices=

The value is the number of devices in a complete active array. As with level= this is mainly for compatibility with the output of mdadm --examine --scan.

spares=

The value is a number of spare devices to expect the array to have. The sole use of this keyword and value is as follows: mdadm --monitor will report an array if it is found to have fewer than this number of spares when --monitor starts or when --oneshot is used.

spare-group=

The value is a textual name for a group of arrays. All arrays with the same spare-group name are considered to be part of the same group. The significance of a group of arrays is that mdadm will, when monitoring the arrays, move a spare drive from one array in a group to another array in that group if the first array had a failed or missing drive but no spare.

bitmap=

The option specifies a file in which a write-intent bitmap should be found. When assembling the array, mdadm will provide this file to the md driver as the bitmap file. This has the same function as the --bitmap-file option to --assemble.

metadata=

Specify the metadata format that the array has. This is mainly recognised for comparability with the output of mdadm -Es.

container=

Specify that this array is a member array of some container. The value given can be either a path name in /dev, or a UUID of the container array.

member=

Specify that this array is a member array of some container. Each type of container has some way to enumerate member arrays, often a simple sequence number. The value identifies which member of a container the array is. It will usually accompany a "container=" word.

MAILADDR

The mailaddr line gives an E-mail address that alerts should be sent to when mdadm is running in --monitor mode (and was given the --scan option). There should only be one MAILADDR line and it should have only one address. Any subsequent addresses are silently ignored.

MAILFROM

The mailfrom line (which can only be abbreviated to at least 5 characters) gives an address to appear in the "From" address for alert mails. This can be useful if you want to explicitly set a domain, as the default from address is "root" with no domain. All words on this line are catenated with spaces to form the address. Note that this value cannot be set via the mdadm commandline. It is only settable via the config file. There should only be one MAILADDR line and it should have only one address. Any subsequent addresses are silently ignored.

PROGRAM

The program line gives the name of a program to be run when mdadm --monitor detects potentially interesting events on any of the arrays that it is monitoring. This program gets run with two or three arguments, they being the Event, the md device, and possibly the related component device. There should only be one program line and it should be given only one program. Any subsequent programs are silently ignored.

CREATE

The create line gives default values to be used when creating arrays, new members of arrays, and device entries for arrays. There should only be one create line. Any subsequent lines will override the previous settings.

Keywords used in the CREATE line and supported values are:

owner=

group=

These can give user/group ids or names to use instead of system defaults (root/wheel or root/disk).

mode=

An octal file mode such as 0660 can be given to override the default of 0600.

metadata=

The name of the metadata format to use if none is explicitly given. This can be useful to impose a system-wide default of version-1 superblocks.

names=yes

It has been possible to create md devices with a name like md_home rather than just a number, like md3. mdadm will use the numeric alternative by default as other tools that interact with md arrays may expect only numbers. If names=yes is given in mdadm.conf then mdadm will use a name when appropriate. If names=no is given, then non-numeric md device names will not be used even if the default changes in a future release of mdadm.

bbl=no

By default, mdadm will reserve space for a bad block list (bbl) on all devices included in or added to any array that supports them. Setting bbl=no will prevent this, so newly added devices will not have a bad block log.

HOMEHOST

The homehost line gives a default value for the --homehost= option to mdadm. There should normally be only one other word on the line. It should either be a host name, or one of the special words <system>, <none> and <ignore>. If <system> is given, then the gethostname(2) systemcall is used to get the host name. This is the default. If <ignore> is given, then a flag is set so that when arrays are being auto-assembled the checking of the recorded homehost is disabled. If <ignore> is given it is also possible to give an explicit name which will be used when creating arrays. This is the only case when there can be more that one other word on the HOMEHOST line. If there are other words, or other HOMEHOST lines, they are silently ignored.

If <none> is given, then the default of using gethostname(2) is over-ridden and no homehost name is assumed.

When arrays are created, this host name will be stored in the metadata. When arrays are assembled using auto-assembly, arrays which do not record the correct homehost name in their metadata will be assembled using a "foreign" name. A "foreign" name alway ends with a digit string preceded by an underscore to differentiate it from any possible local name. e.g. /dev/md/1_1 or /dev/md/home_0.

HOMECLUSTER

The homcluster line gives a default value for the --homecluster= option to mdadm. It specifies the cluster name for the md device. The md device can be assembled only on the cluster which matches the name specified. If homcluster is not provided, mdadm tries to detect the cluster name automatically. There should only be one homecluster line. Any subsequent lines will be silently ignored.

AUTO

A list of names of metadata format can be given, each preceded by a plus or minus sign. Also the word homehost is allowed as is all preceded by plus or minus sign. all is usually last. When mdadm is auto-assembling an array, either via --assemble or --incremental and it finds metadata of a given type, it checks that metadata type against those listed in this line. The first match wins, where all matches anything. If a match is found that was preceded by a plus sign, the auto assembly is allowed. If the match was preceded by a minus sign, the auto assembly is disallowed. If no match is found, the auto assembly is allowed.

If the metadata indicates that the array was created for this host, and the word homehost appears before any other match, then the array is treated as a valid candidate for auto-assembly.

This can be used to disable all auto-assembly (so that only arrays explicitly listed in mdadm.conf or on the command line are assembled), or to disable assembly of certain metadata types which might be handled by other software. It can also be used to disable assembly of all foreign arrays - normally such arrays are assembled but given a non-deterministic name in /dev/md/.

The known metadata types are 0.90, 1.x, ddf, imsm.

AUTO should be given at most once. Subsequent lines are silently ignored. Thus a later config file in a config directory will not overwrite the setting in an earlier config file.

POLICY

This is used to specify what automatic behavior is allowed on devices newly appearing in the system and provides a way of marking spares that can be moved to other arrays as well as the migration domains. Domain can be defined through policy line by specifying a domain name for a number of paths from /dev/disk/by-path/. A device may belong to several domains. The domain of an array is a union of domains of all devices in that array. A spare can be automatically moved from one array to another if the set of the destination array's domains contains all the domains of the new disk or if both arrays have the same spare-group. To update hot plug configuration it is necessary to execute mdadm --udev-rules=<path_to_file> e.g. /etc/udev/rules.d/65-md-bare.rules command after changing the config file. And also run udevadm control --reload otherwise, a reboot is needed.

Keywords used in the POLICY line and supported values are:

domain=

any arbitrary string

metadata=

0.9 1.x ddf or imsm

path=

file glob matching anything from /dev/disk/by-path

type=

either disk or part.

action=

include, re-add, spare, spare-same-slot, or force-spare

auto=

yes, no, or homehost.

The action item determines the automatic behavior allowed for devices matching the path and type in the same line. If a device matches several lines with different actions then the most permissive will apply. The ordering of policy lines is irrelevant to the end result.

include

allows adding a disk to an array if metadata on that disk matches that array

re-add

will include the device in the array if it appears to be a current member or a member that was recently removed and the array has a write-intent-bitmap to allow the re-add functionality.

spare

as above and additionally: if the device is bare it can become a spare if there is any array that it is a candidate for based on domains and metadata.

spare-same-slot

as above and additionally if given slot was used by an array that went degraded recently and the device plugged in has no metadata then it will be automatically added to that array (or it's container)

force-spare

as above and the disk will become a spare in remaining cases

PART-POLICY

This is similar to POLICY and accepts the same keyword assignments. It allows a consistent set of policies to applied to each of the partitions of a device. A PART-POLICY line should set type=disk and identify the path to one or more disk devices. Each partition on these disks will be treated according to the action= setting from this line. If a domain is set in the line, then the domain associated with each patition will be based on the domain, but with "-partN" appended, when N is the partition number for the partition that was found.

SYSFS

The SYSFS line lists custom values of MD device's sysfs attributes which will be stored in sysfs after the array is assembled. Multiple lines are allowed and each line has to contain the uuid or the name of the device to which it relates. Lines are applied in reverse order.

uuid=

hexadecimal identifier of MD device. This has to match the uuid stored in the superblock.

name=

name of the MD device as was given to mdadm when the array was created. It will be ignored if uuid is not empty.

MONITORDELAY

The monitordelay line gives a delay in seconds mdadm shall wait before pooling md arrays when mdadm is running in --monitor mode. -d/--delay command line argument takes precedence over the config file. If multiple MINITORDELAY lines are provided, only first non-zero value is considered.

ENCRYPTION_NO_VERIFY

The ENCRYPTION_NO_VERIFY disables encryption verification for devices with particular encryption support detected. Currently, only verification of SATA OPAL encryption can be disabled. It does not disable ATA security encryption verification. Currently effective only for IMSM metadata. Available parameter sata_opal .

PROBING

The PROBING line provides options to configure device probing.

ddf_extended

Use extended algorithm to detect DDF headers on disks. Instead of looking for the DDF super block only in the last block of the device, scan the last 32 MB. This allows detection of metadata created by some RAID controllers, at the cost of slower probing.

## FILES

### /etc/mdadm.conf
The default config file location, used when mdadm is running without --config option.

### /etc/mdadm.conf.d
The default directory with config files. Used when mdadm is running without --config option, after successful reading of the /etc/mdadm.conf default config file. Files in that directory are read in lexical order.

### /etc/mdadm/mdadm.conf
Alternative config file that is read, when mdadm is running without --config option and the /etc/mdadm.conf default config file was not opened successfully.

### /etc/mdadm/mdadm.conf.d
The alternative directory with config files. Used when mdadm is runninng without --config option, after reading the /etc/mdadm/mdadm.conf alternative config file whether it was successful or not. Files in that directory are read in lexical order.

## EXAMPLE
DEVICE /dev/sd[bcdjkl]1

DEVICE /dev/hda1 /dev/hdb1

\# /dev/md0 is known by its UUID.

ARRAY /dev/md0 UUID=3aaa0122:29827cfa:5331ad66:ca767371

\# /dev/md1 contains all devices with a minor number of

\# 1 in the superblock.

ARRAY /dev/md1 superminor=1

\# /dev/md2 is made from precisely these two devices

ARRAY /dev/md2 devices=/dev/hda1,/dev/hdb1

\# /dev/md4 and /dev/md5 are a spare-group and spares

\# can be moved between them

ARRAY /dev/md4 uuid=b23f3c6d:aec43a9f:fd65db85:369432df

spare-group=group1

ARRAY /dev/md5 uuid=19464854:03f71b1b:e0df2edd:246cc977

spare-group=group1

\# /dev/md/home is created if need to be a partitionable md array

\# any spare device number is allocated.

ARRAY /dev/md/home UUID=9187a482:5dde19d9:eea3cc4a:d646ab8b

auto=part

\# One domain comprising of devices attached to specified paths is defined.

\# Bare device matching first path will be made an imsm spare on hot plug.

\# If more than one array is created on devices belonging to domain1 and

\# one of them becomes degraded, then any imsm spare matching any path for

\# given domain name can be migrated.

POLICY domain=domain1 metadata=imsm path=pci-0000:00:1f.2-scsi-*

action=spare

POLICY domain=domain1 metadata=imsm path=pci-0000:04:00.0-scsi-[01]*

action=include

MAILADDR root@mydomain.tld

PROGRAM /usr/sbin/handle-mdadm-events

CREATE group=system mode=0640 auto=part-8

HOMEHOST <system>

AUTO +1.x homehost -all

SYSFS name=/dev/md/raid5 group_thread_cnt=4 sync_speed_max=1000000

SYSFS uuid=bead5eb6:31c17a27:da120ba2:7dfda40d group_thread_cnt=4 sync_speed_max=1000000

MONITORDELAY 60

ENCRYPTION_NO_VERIFY sata_opal

## SEE ALSO
mdadm(8), md(4).


megarc

package: megatools

title: megarc(5)

summary: Configuration file for megatools

text:
# megarc(5)

## NAME
megarc - Configuration file for megatools

## SYNOPSIS

```
~/.megarc
./.megarc
```

## DESCRIPTION
Megatools use INI configuration file to store commonly used login credentials. This makes it less bothersome to use the tools, as you can simply write

```
$ megadf
```

instead of

```
$ megadf --username my@email.com --password mypass
```

when using the tools.

Configuration file is read either from the current directory or user’s home directory. Exceptions are when --ignore-config-file was passed to the tool, or when explicit path to the config file was given via --config <path>.

## CONFIG FILE SECTIONS
All sections are optional. All names are case sensitive, thus you must write [Login], and not [login], and so on.

### [Login] Section
Username

Your username.

Password

Your password. Be aware that back slashes have special meaning. If you have back slash in your password, you must escape it with another backslash. For example: my\nice\password would be written as my\\nice\\password in the config file.

### [Cache] Section
Timeout

Cache timeout in seconds (default is 10 minutes).

### [Network] Section
DownloadSpeedLimit

Set maximum allowed download speed in KiB/s. 0 means no limit. Overrides SpeedLimit setting.

UploadSpeedLimit

Set maximum allowed upload speed in KiB/s. 0 means no limit. Overrides SpeedLimit setting. When using ParallelTransfers > 1, upload speed limit is applied to each transfer individually.

SpeedLimit

Set maximum allowed upload and download speed in KiB/s. 0 means no limit.

ParallelTransfers

Set maximum allowed number of parallel connections when upload or downloading a file. The file is split into chunks of a size between 128 kiB and 1 MiB, and these chunks are uploaded in parallel. The number must be between 1 and 16. Default is 5.

Proxy

Use proxy server to connect to mega.nz. More information can be found in libcurl documentation at https://curl.haxx.se/libcurl/c/CURLOPT_PROXY.html. Some acceptable values are:

•socks5://localhost:9050 : Local SOCKSv5 proxy server

•socks5h://localhost:9050 : Local SOCKSv5 proxy server with DNS handled by the proxy

### [Upload] Section
CreatePreviews

Create Previews (see --enable-previews option).

## EXAMPLE
Create ~/.megarc (on linux) or mega.ini file containing these 3 lines:

```
[Login]
Username = your@email
Password = yourpassword
[Network]
# 1MiB/s
SpeedLimit = 1024
# Use over TOR
Proxy = socks5://127.0.0.1:9050
ParallelTransfers = 2
```

Run megadf(1) to check that megatools are able to login to your account.

## SEE ALSO
megatools(7), megarc(5), megadf(1), megadl(1), megaget(1), megals(1), megamkdir(1), megaput(1), megareg(1), megarm(1), megacopy(1).

## MEGATOOLS
Part of the megatools(7) suite.

## BUGS
Report bugs at https://github.com/megous/megatools or megous@megous.com.

## AUTHOR
Megatools was written by Ondrej Jirman <megous@megous.com>, 2013-2016.

Official website is http://megatools.megous.com.


menufile

package: menu

title: menufile(5)

summary: entry in the Debian menu system

text:
# menufile(5)

## NAME
menufile - entry in the Debian menu system

## SYNOPSIS
~/.menu/*

/etc/menu/*

/usr/lib/menu/*

/usr/share/menu/*

/usr/share/menu/default/*

## DESCRIPTION
Menu files add entries to the Debian menu system. The system administrator can place menu files in /etc/menu/ to override menu files that packages add to /usr/share/menu/ . The user can place menu files in ~/.menu/ to override all other menu files.

Please read the Debian menu manual available in /usr/share/doc/menu/html for the complete specification of menu files.

The menu files are usually named after the Debian package that contains the programs listed in them. In it, you can list several "menu entries" that specify a specific item in the menu structure. Each menu entry specifies which packages it depends on; if that package are not installed, the menu entry will be ignored by update-menus(1). (In a menu entry you can specify pseudo-packages that start with "local."; update-menus will always use those menu entries). If you wish to remove an item from the menu entirely, make an empty menu file with the same name as the file you want to override.

## Examples
Dosemu could install the following menu file as /usr/share/menu/dosemu:

?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu" command="dosemu"

?package(dosemu):needs="X11" section="Applications/Emulators" title="Dosemu" command="xdos"

The system administrator wants to override this file to change how dosemu is run, so /etc/menu/dosemu is created:

?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu" command="dosemu -A"

?package(dosemu):needs="X11" section="Applications/Emulators" title="Dosemu" command="xdos -A"

A user does not want Dosemu to appear in the menus at all, so the user creates an empty file named ~/.menu/dosemu.

## FORMAT
A menu file consists of 0 or more lines of the following format:

?package(package-name):var1=value1 var2=value2 ...

needs

Specify what kind of environment the program require. This variable must be defined, and should be one of the following:

needs="text"

Program requires a terminal

needs="x11"

Program requires a X server

needs="vc"

Program requires a Linux console (i.e.: svgalib programs)

needs="wm"

The program is a window manager.

needs="fvwmmodule"

The program is a fvwm compatible module.

section

The section in which the menu entry should appear. See MENU LAYOUT for preferred section names.

icon

An icon for this menu entry. If no icon is available, just don't define this.

title

The title of the program that will appear on the menus. Keep it short. If two menu entries share the same title and section, the one that best fits the available display will be used. So in the example above with two menu entries that both have the menu id "title", if X is available, the X11 one will be used; otherwise the text one will be used. Must be defined.

command

The command to be executed when this menu entry is selected.

hints

A comma-separated list of hints on how grouping menu entries; see the manual.

## MENU LAYOUT
The authoritative list of Debian's menu structure is maintained in the Debian Menu sub-policy document which is part of the Debian Policy package. The menu structure below is included only for convenience. Please do not put your packages into any other sections.

Use `/' to separate sub-menu names, for example, "Applications/Editors" or "Games/Arcade".

Applications

Accessibility

Amateur Radio

Data Management

Editors

Education

Emulators

File Management

Graphics

Mobile Devices

Network

Communication

File Transfer

Monitoring

Web Browsing

Web News

Office

Programming

Project Management

Science

Astronomy

Biology

Chemistry

Data Analysis

Electronics

Engineering

Geoscience

Mathematics

Medicine

Physics

Social

Shells

Sound

System

Administration

Hardware

Language Environment

Monitoring

Package Management

Security

Terminal Emulators

Text

TV and Radio

Viewers

Video

Web Development

Games

Action

Adventure

Blocks

Board

Card

Puzzles

Simulation

Strategy

Tools

Toys

Help

Screen

Saving

Locking

Window Managers

FVWM Modules

Window Maker

## NOTES
If you want to specify an icon or hotkey for a sub-menu (for example, the Editors sub-menu), just use the same syntax but leave the command empty:

?package(mypackage):needs="X11" section="Applications" icon="icon.xpm" hotkey="E" title="Editors"

Whenever any menu files are changed, you must run update-menus(1)

## FILES
(Earlier listed files override later files with the same names.)

~/.menu/*

Menu files added by the user.

/etc/menu/* Menu files added by the system administrator.

/usr/lib/menu/* Architecture-dependant menu files provided by other Debian packages.

/usr/share/menu/* Architecture-independant menu files provided by other Debian packages.

/usr/share/menu/default/* Menu files provided by the menu package.

## AUTHORS
Joost Witteveen <joostje@debian.org>, based on work by Lars Wirzenius <liw@iki.fi>. Now maintained by Bill Allombert <ballombe@debian.org>.

(Man page by Joey Hess, <joeyh@debian.org>)

## SEE ALSO
update-menus(1), /usr/share/doc/menu/html/index.html


menufile.fr

title: menufile.fr(5)

summary: entr�e dans le syst�me des menus Debian

text:
# menufile.fr(5)

## NOM
menufile - entrée dans le système des menus Debian

## SYNOPSIS
~/.menu/*

/etc/menu/*

/usr/lib/menu/*

/usr/share/menu/*

/usr/share/menu/default/*

## DESCRIPTION
Les fichiers de menus ajoutent des entrées dans le système des menus Debian. L'administrateur système peut placer des fichiers de menus dans /etc/menu/ qui auront priorité sur les fichiers de menus que les paquets ajoutent à /usr/share/menu/. Un utilisateur peut placer des fichiers de menus dans ~/.menu/ qui auront priorité sur tous les autres fichiers de menus.

Veuillez consulter le manuel des menus Debian présent dans /usr/share/doc/menu/html pour les spécifications complètes des fichiers de menus.

Les fichiers de menus portent d'habitude le nom du paquet Debian qui contient les programmes qu'ils listent. Ils peuvent contenir plusieurs « entrées de menus », qui spécifient un élément particulier de la structure d'un menu. Chaque entrée de menu spécifie les paquets dont elle dépend, ce qui permet à update-menus(1) d'ignorer le menu si ces paquets ne sont pas installés. (Dans une entrée de menu vous pouvez spécifier des pseudo-paquets qui commencent par « local. », ce qui indique à update-menus de toujours utiliser ces menus). Si vous voulez supprimer entièrement tous les éléments d'un fichier de menus, vous pouvez créer un fichier vide portant le même nom que ce fichier de menus.

## Exemples
Dosemu peut installer le fichier de menus suivant dans /usr/share/menu/dosemu :

?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu" command="dosemu"

?package(dosemu):needs="x11" section="Applications/Emulators" title="Dosemu" command="xdos"

L'administrateur système peut vouloir remplacer ce fichier pour changer la façon dont dosemu est exécuté, il crée alors le fichier /etc/menu/dosemu suivant :

?package(dosemu):needs="text" section="Applications/Emulators" title="Dosemu" command="dosemu -A"

?package(dosemu):needs="x11" section="Applications/Emulators" title="Dosemu" command="xdos -A"

Il se peut également qu'un utilisateur ne veuille pas voir apparaître Dosemu dans ses menus. Il peut alors créer un fichier vide nommé ~/.menu/dosemu.

## FORMAT
Un fichier de menus consiste en 0 ou plusieurs lignes dans le format suivant :

?package(nom_paquet):var1=value1 var2=value2 ...

needs

Indique le type d'environnement que le programme nécessite. Cette variable est obligatoire et peut valoir :

needs="text"

Le programme nécessite un terminal

needs="x11"

Le programme nécessite un serveur X

needs="vc"

Le programme nécessite une console Linux (c'est à dire un programme utilisant svgalib).

needs="wm"

Le programme est un gestionnaire de fenêtres.

needs="fvwmmodule"

Le programme est un module compatible avec fvwm.

section

La section dans laquelle l'entrée de menu doit être affichée. Reportez-vous à la section DISPOSITION DES MENUS pour les noms de section.

icon

Une icône pour cette entrée de menu. Si aucune icône n'est disponible, il suffit de ne pas définir ce champ. (icon="none" est également possible, mais il est préférable de ne pas placer cette ligne).

title

Le titre du programme qui apparaîtra dans le menu. Essayez de garder ce champ court. Si deux entrées de menu partagent le même titre et la même section, celle qui est la mieux adaptée au type d'affichage est conservée. De cette façon, dans l'exemple précédent qui a deux menus qui ont le même titre, si X est disponible, l'entrée dépendant de X11 est utilisée, sinon celle pour un affichage texte est utilisée. Ce champ est obligatoire.

command

La commande à exécuter lorsque cette entrée est sélectionnée.

hints

Une liste d'indications séparées par des virgules, permettant de grouper les menus. Veuillez consulter le manuel.

## DISPOSITION DES MENUS
La liste officielle de la structure des menus Debian est maintenue dans la sous-charte des menus Debian (« Debian Menu sub-policy »), qui fait partie du paquet Debian Policy. La structure de menus ci-dessous est incluse (et traduite) pour des raisons de commodité. Veuillez ne pas placer vos paquets dans d'autres sections.

NDT : les noms de sections officiels sont automatiquement traduits au moment de la génération des menus.

Utilisez `/' pour séparer les noms des sous-menus. Par exemple : "Applications/Editors" ou "Games/Action".

Applications

Accessibility

Amateur Radio

Data Management

Editors

Education

Emulators

File Management

Graphics

Mobile Devices

Network

Communication

File Transfer

Monitoring

Web Browsing

Web News

Office

Programming

Project Management

Science

Astronomy

Biology

Chemistry

Data Analysis

Electronics

Engineering

Geoscience

Mathematics

Medicine

Physics

Social

Shells

Sound

System

Administration

Hardware

Language Environment

Monitoring

Package Management

Security

Terminal Emulators

Text

TV and Radio

Viewers

Video

Web Development

Games

Action

Adventure

Blocks

Board

Card

Puzzles

Simulation

Strategy

Tools

Toys

Help

Screen

Saving

Locking

Window Managers

FVWM Modules

Window Maker

## NOTES
Si vous voulez spécifier une icône ou un raccourci clavier pour un sous-menu (par exemple, le sous-menu Editors), utilisez la même syntaxe, mais laissez le champ command vide, comme ceci :

?package(monpaquet):needs="X11" section="Applications" icon="icon.xpm" hotkey="E" title="Editors"

À chaque fois qu'un fichier de menus est modifié, vous devez exécuter update-menus(1).

## FICHIERS
(Fichiers par ordre de priorité décroissante)

~/.menu/*

Fichiers de menus ajoutés par l'utilisateur.

/etc/menu/* Fichiers de menus ajoutés par l'administrateur système.

/usr/lib/menu/* Fichiers de menus dépendants de l'architecture fournis par d'autres paquets Debian.

/usr/share/menu/* Fichiers de menus indépendants de l'architecture fournis par d'autres paquets Debian.

/usr/share/menu/default/* Fichiers de menus fournis par le paquet menu.

## AUTEURS
Joost Witteveen <joostje@debian.org>, basé sur les travaux de Lars Wirzenius <liw@iki.fi>. Il est désormais maintenu par Bill Allombert <ballombe@debian.org>.

Page de manuel par Joey Hess, <joeyh@debian.org>

Ce document est basé sur une traduction réalisée par Nicolas François le 3 septembre 2005.

## VOIR AUSSI
update-menus(1), /usr/share/doc/menu/html/index.html


hgignore

package: mercurial

title: hgignore(5)

summary: syntax for Mercurial ignore files

text:
# hgignore(5)

## NAME
hgignore - syntax for Mercurial ignore files

## SYNOPSIS
The Mercurial system uses a file called .hgignore in the root directory of a repository to control its behavior when it searches for files that it is not currently tracking.

## DESCRIPTION
The working directory of a Mercurial repository will often contain files that should not be tracked by Mercurial. These include backup files created by editors and build products created by compilers. These files can be ignored by listing them in a .hgignore file in the root of the working directory. The .hgignore file must be created manually. It is typically put under version control, so that the settings will propagate to other repositories with push and pull.

An untracked file is ignored if its path relative to the repository root directory, or any prefix path of that path, is matched against any pattern in .hgignore.

For example, say we have an untracked file, file.c, at a/b/file.c inside our repository. Mercurial will ignore file.c if any pattern in .hgignore matches a/b/file.c, a/b or a.

In addition, a Mercurial configuration file can reference a set of per-user or global ignore files. See the ignore configuration key on the [ui] section of hg help config for details of how to configure these files.

To control Mercurial's handling of files that it manages, many commands support the -I and -X options; see hg help <command> and hg help patterns for details.

Files that are already tracked are not affected by .hgignore, even if they appear in .hgignore. An untracked file X can be explicitly added with hg add X, even if X would be excluded by a pattern in .hgignore.

## SYNTAX
An ignore file is a plain text file consisting of a list of patterns, with one pattern per line. Empty lines are skipped. The # character is treated as a comment character, and the \ character is treated as an escape character.

Mercurial supports several pattern syntaxes. The default syntax used is Python/Perl-style regular expressions.

To change the syntax used, use a line of the following form:

```
syntax: NAME
```

where NAME is one of the following:

regexp

Regular expression, Python/Perl syntax.

glob

Shell-style glob.

rootglob

A variant of glob that is rooted (see below).

The chosen syntax stays in effect when parsing all patterns that follow, until another syntax is selected.

Neither glob nor regexp patterns are rooted. A glob-syntax pattern of the form *.c will match a file ending in .c in any directory, and a regexp pattern of the form \.c$ will do the same. To root a regexp pattern, start it with ^. To get the same effect with glob-syntax, you have to use rootglob.

Subdirectories can have their own .hgignore settings by adding subinclude:path/to/subdir/.hgignore to the root .hgignore. See hg help patterns for details on subinclude: and include:.

Note

Patterns specified in other than .hgignore are always rooted. Please see hg help patterns for details.

## EXAMPLE
Here is an example ignore file.

```
# use glob syntax.
syntax: glob
*.elc
*.pyc
*~
# switch to regexp syntax.
syntax: regexp
^\.pc/
```

## DEBUGGING
Use the debugignore command to see if and why a file is ignored, or to see the combined ignore pattern. See hg help debugignore for details.

## AUTHOR
Vadim Gelfer <vadim.gelfer@gmail.com>

Mercurial was written by Olivia Mackall <olivia@selenic.com>.

## SEE ALSO
hg(1), hgrc(5)

## COPYING
This manual page is copyright 2006 Vadim Gelfer. Mercurial is copyright 2005-2026 Olivia Mackall. Free use of this software is granted under the terms of the GNU General Public License version 2 or any later version.

## AUTHOR
Vadim Gelfer <vadim.gelfer@gmail.com>

Organization: Mercurial