ntp.keys

title: ntp.keys(5)

summary: NTP symmetric key file format

text:
# ntp.keys(5)

## NAME
ntp.keys - NTP symmetric key file format configuration file

## SYNOPSIS
[--option-name] [--option-name value]

All arguments must be options.

## DESCRIPTION
This document describes the format of an NTP symmetric key file. For a description of the use of this type of file, see the "Authentication Support" section of the ntp.conf(5) page.

ntpd(8) reads its keys from a file specified using the -k command line option or the keys statement in the configuration file. While key number 0 is fixed by the NTP standard (as 56 zero bits) and may not be changed, one or more keys numbered between 1 and 65535 may be arbitrarily set in the keys file.

The key file uses the same comment conventions as the configuration file. Key entries use a fixed format of the form

keyno type key opt_IP_list

where keyno is a positive integer (between 1 and 65535), type is the message digest algorithm, key is the key itself, and opt_IP_list is an optional comma-separated list of IPs where the keyno should be trusted. that are allowed to serve time. Each IP in opt_IP_list may contain an optional /subnetbits specification which identifies the number of bits for the desired subnet of trust. If opt_IP_list is empty, any properly-authenticated message will be accepted.

The key may be given in a format controlled by the type field. The type MD5 is always supported. If ntpd was built with the OpenSSL library then any digest library supported by that library may be specified. However, if compliance with FIPS 140-2 is required the type must be either SHA or SHA1.

What follows are some key types, and corresponding formats:

MD5

The key is 1 to 16 printable characters terminated by an EOL, whitespace, or a # (which is the "start of comment" character).

SHA

SHA1

RMD160

The key is a hex-encoded ASCII string of 40 characters, which is truncated as necessary.

Note that the keys used by the ntpq(8) and ntpdc(8) programs are checked against passwords requested by the programs and entered by hand, so it is generally appropriate to specify these keys in ASCII format.

## FILES
/etc/ntp.keys

the default name of the configuration file

## SEE ALSO
ntp.conf(5), ntpd(1), ntpdate(1), ntpdc(1), sntp(1)

## AUTHORS
The University of Delaware and Network Time Foundation

## COPYRIGHT
Copyright (C) 1992-2024 The University of Delaware and Network Time Foundation all rights reserved. This program is released under the terms of the NTP license, <http://ntp.org/license>.

## BUGS
Please send bug reports to: https://bugs.ntp.org, bugs@ntp.org

## NOTES
This document was derived from FreeBSD.

This manual page was AutoGen-erated from the ntp.keys option definitions.


nut.conf

package: nut

title: nut.conf(5)

summary: UPS definitions for Network UPS Tools

text:
# nut.conf(5)

## NAME
nut.conf - UPS definitions for Network UPS Tools

## DESCRIPTION
This file attempts to standardize the various files being found in different installations, like /etc/default/nut on Debian based systems and /etc/sysconfig/ups on RedHat based systems.

Distribution’s init script should source this file in order to determine which components have to be started.

Blank lines are ignored. Lines with a hash (#) character at the 1st position of the line are ignored, too. They can be used to add comments.

## IMPORTANT NOTE
This file is intended to be sourced by shell scripts. You MUST NOT use spaces around the equal sign!

Refer to the EXAMPLE section for illustrations.

## DIRECTIVES
MODE

Required. Recognized values are none, standalone, netserver and netclient. Defaults to none. none

Indicates that NUT should not get started automatically, possibly because it is not configured or that an Integrated Power Management or some external system, is used to startup the NUT components.

standalone

Addresses a local only configuration, with 1 UPS protecting the local system. This implies to start the 3 NUT layers (driver, upsd and upsmon), with the related configuration files. This mode can also address UPS redundancy.

netserver

Like the standalone configuration, but also possibly need one or more specific LISTEN directive(s) in upsd.conf. Since this MODE is open to the network, a special care should be applied to security concerns.

netclient

When only upsmon is required, possibly because there are other hosts that are more closely attached to the UPS, the MODE should be set to netclient.

UPSD_OPTIONS

Optional. Set upsd specific options. See upsd(8) for more details. It is ignored when MODE above indicates that no upsd should be running.

UPSMON_OPTIONS

Optional. Set upsmon specific options. See upsmon(8) for more details. It is ignored when MODE above indicates that no upsmon should be running.

POWEROFF_WAIT

Optional. At the end of an emergency system halt, the upsmon master will signal the UPS to switch off. This may fail for a number of reasons. Most notably is the case that mains power returns during the shutdown process. See the section "Power races" in /usr/share/doc/nut/FAQ.txt.gz. The system will wait this long for the UPS to cut power, and then reboot. It should be long enough to exhaust the batteries, in case line power continues to be unavailable. On the other hand, it should not be so long that the system remains offline for an unreasonable amount of time if line power has returned. See sleep(1) for compatible time syntax. If you specify the time in seconds, use the "s" suffix.

Warning this workaround might be dangerous under some circumstances. Please read http://bugs.debian.org/358696 for more details.

## EXAMPLE

```
# /etc/nut/nut.conf.  See nut.conf(5)
```

```
MODE=none
```

```
UPSD_OPTIONS=""
```

```
UPSMON_OPTIONS=""
```

```
# POWEROFF_WAIT=15m
```

## INTEGRATION
An init script, such as /etc/init.d/nut, is expected to source this file in order to determine which component(s) has to be started.

## SEE ALSO
ups.conf(5), upsd.conf(5), upsd.users(5), upsmon.conf(5)

## INTERNET RESOURCES
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upsmon.conf

title: upsmon.conf(5)

text:
# upsmon.conf(5)

## NAME
upsmon.conf - Configuration for Network UPS Tools upsmon

## DESCRIPTION
This file’s primary job is to define the systems that upsmon(8) will monitor and to tell it how to shut down the system when necessary. It will contain passwords, so keep it secure. Ideally, only the upsmon process should be able to read it.

Additionally, other optional configuration values can be set in this file.

## CONFIGURATION DIRECTIVES
DEADTIME seconds

upsmon allows a UPS to go missing for this many seconds before declaring it "dead". The default is 15 seconds. upsmon requires a UPS to provide status information every few seconds (see POLLFREQ and POLLFREQALERT) to keep things updated. If the status fetch fails, the UPS is marked stale. If it stays stale for more than DEADTIME seconds, the UPS is marked dead.

A dead UPS that was last known to be on battery is assumed to have changed to a low battery condition. This may force a shutdown if it is providing a critical amount of power to your system. This seems disruptive, but the alternative is barreling ahead into oblivion and crashing when you run out of power.

Note: DEADTIME should be a multiple of POLLFREQ and POLLFREQALERT. Otherwise, you’ll have "dead" UPSes simply because upsmon isn’t polling them quickly enough. Rule of thumb: take the larger of the two POLLFREQ values, and multiply by 3.

FINALDELAY seconds

When running in master mode, upsmon waits this long after sending the NOTIFY_SHUTDOWN to warn the users. After the timer elapses, it then runs your SHUTDOWNCMD. By default this is set to 5 seconds. If you need to let your users do something in between those events, increase this number. Remember, at this point your UPS battery is almost depleted, so don’t make this too big.

Alternatively, you can set this very low so you don’t wait around when it’s time to shut down. Some UPSes don’t give much warning for low battery and will require a value of 0 here for a safe shutdown.

Note

If FINALDELAY on the slave is greater than HOSTSYNC on the master, the master will give up waiting for the slave to disconnect.

HOSTSYNC seconds

upsmon will wait up to this many seconds in master mode for the slaves to disconnect during a shutdown situation. By default, this is 15 seconds. When a UPS goes critical (on battery + low battery, or "FSD": forced shutdown), the slaves are supposed to disconnect and shut down right away. The HOSTSYNC timer keeps the master upsmon from sitting there forever if one of the slaves gets stuck.

This value is also used to keep slave systems from getting stuck if the master fails to respond in time. After a UPS becomes critical, the slave will wait up to HOSTSYNC seconds for the master to set the FSD flag. If that timer expires, the slave will assume that the master is broken and will shut down anyway.

This keeps the slaves from shutting down during a short-lived status change to "OB LB" that the slaves see but the master misses.

MINSUPPLIES num

Set the number of power supplies that must be receiving power to keep this system running. Normal computers have just one power supply, so the default value of 1 is acceptable. Large/expensive server type systems usually have more, and can run with a few missing. The HP NetServer LH4 can run with 2 out of 4, for example, so you’d set it to 2. The idea is to keep the box running as long as possible, right?

Obviously you have to put the redundant supplies on different UPS circuits for this to make sense! See big-servers.txt in the docs subdirectory for more information and ideas on how to use this feature.

Also see the section on "power values" in upsmon(8).

MONITOR system powervalue username password type

Each UPS that you need to be monitor should have a MONITOR line. Not all of these need supply power to the system that is running upsmon. You may monitor other systems if you want to be able to send notifications about status changes on them.

You must have at least one MONITOR directive in upsmon.conf.

system is a UPS identifier. It is in this form:

<upsname>[@<hostname>[:<port>]]

The default hostname is "localhost". Some examples:

•"su700@mybox" means a UPS called "su700" on a system called "mybox". This is the normal form.

•"fenton@bigbox:5678" is a UPS called "fenton" on a system called "bigbox" which runs upsd(8) on port "5678".

powervalue is an integer representing the number of power supplies that the UPS feeds on this system. Most normal computers have one power supply, and the UPS feeds it, so this value will be 1. You need a very large or special system to have anything higher here.

You can set the powervalue to 0 if you want to monitor a UPS that doesn’t actually supply power to this system. This is useful when you want to have upsmon do notifications about status changes on a UPS without shutting down when it goes critical.

The username and password on this line must match an entry in that system’s upsd.users(5). If your username is "monmaster" and your password is "blah", the MONITOR line might look like this:

MONITOR myups@bigserver 1 monmaster blah master

Meanwhile, the upsd.users on bigserver would look like this:

```
[monmaster]

        password  = blah

        upsmon master #  (or slave)
```

The type refers to the relationship with upsd(8). It can be either "master" or "slave". See upsmon(8) for more information on the meaning of these modes. The mode you pick here also goes in the upsd.users file, as seen in the example above.

NOCOMMWARNTIME seconds

upsmon will trigger a NOTIFY_NOCOMM after this many seconds if it can’t reach any of the UPS entries in this configuration file. It keeps warning you until the situation is fixed. By default this is 300 seconds.

NOTIFYCMD command

upsmon calls this to send messages when things happen. This command is called with the full text of the message as one argument. The environment string NOTIFYTYPE will contain the type string of whatever caused this event to happen.

If you need to use upssched(8), then you must make it your NOTIFYCMD by listing it here.

Note that this is only called for NOTIFY events that have EXEC set with NOTIFYFLAG. See NOTIFYFLAG below for more details.

Making this some sort of shell script might not be a bad idea. For more information and ideas, see docs/scheduling.txt

Remember, this command also needs to be one element in the configuration file, so if your command has spaces, then wrap it in quotes.

NOTIFYCMD "/path/to/script --foo --bar"

This script is run in the background—that is, upsmon forks before it calls out to start it. This means that your NOTIFYCMD may have multiple instances running simultaneously if a lot of stuff happens all at once. Keep this in mind when designing complicated notifiers.

NOTIFYMSG type message

upsmon comes with a set of stock messages for various events. You can change them if you like.

```
NOTIFYMSG ONLINE "UPS %s is getting line power"
```

```
NOTIFYMSG ONBATT "Someone pulled the plug on %s"
```

Note that %s is replaced with the identifier of the UPS in question.

The message must be one element in the configuration file, so if it contains spaces, you must wrap it in quotes.

```
NOTIFYMSG NOCOMM "Someone stole UPS %s"
```

Possible values for type:

ONLINE

UPS is back online

ONBATT

UPS is on battery

LOWBATT

UPS is on battery and has a low battery (is critical)

FSD

UPS is being shutdown by the master (FSD = "Forced Shutdown")

COMMOK

Communications established with the UPS

COMMBAD

Communications lost to the UPS

SHUTDOWN

The system is being shutdown

REPLBATT

The UPS battery is bad and needs to be replaced

NOCOMM

A UPS is unavailable (can’t be contacted for monitoring)

NOTIFYFLAG type flag[+flag][+flag]...

By default, upsmon sends walls global messages to all logged in users) via /bin/wall and writes to the syslog when things happen. You can change this. Examples:

```
NOTIFYFLAG ONLINE SYSLOG
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
```

Possible values for the flags:

SYSLOG

Write the message to the syslog

WALL

Write the message to all users with /bin/wall

EXEC

Execute NOTIFYCMD (see above) with the message

IGNORE

Don’t do anything If you use IGNORE, don’t use any other flags on the same line.

POLLFREQ seconds

Normally upsmon polls the upsd(8) server every 5 seconds. If this is flooding your network with activity, you can make it higher. You can also make it lower to get faster updates in some cases. There are some catches. First, if you set the POLLFREQ too high, you may miss short-lived power events entirely. You also risk triggering the DEADTIME (see above) if you use a very large number.

Second, there is a point of diminishing returns if you set it too low. While upsd normally has all of the data available to it instantly, most drivers only refresh the UPS status once every 2 seconds. Polling any more than that usually doesn’t get you the information any faster.

POLLFREQALERT seconds

This is the interval that upsmon waits between polls if any of its UPSes are on battery. You can use this along with POLLFREQ above to slow down polls during normal behavior, but get quicker updates when something bad happens. This should always be equal to or lower than the POLLFREQ value. By default it is also set 5 seconds.

The warnings from the POLLFREQ entry about too-high and too-low values also apply here.

POWERDOWNFLAG filename

upsmon creates this file when running in master mode when the UPS needs to be powered off. You should check for this file in your shutdown scripts and call upsdrvctl shutdown if it exists. This is done to forcibly reset the slaves, so they don’t get stuck at the "halted" stage even if the power returns during the shutdown process. This usually does not work well on contact-closure UPSes that use the genericups driver.

See the config-notes.txt file in the docs subdirectory for more information. Refer to the section:

"Configuring automatic shutdowns for low battery events", or refer to the online version.

RBWARNTIME seconds

When a UPS says that it needs to have its battery replaced, upsmon will generate a NOTIFY_REPLBATT event. By default, this happens every 43200 seconds (12 hours). If you need another value, set it here.

RUN_AS_USER username

upsmon normally runs the bulk of the monitoring duties under another user ID after dropping root privileges. On most systems this means it runs as "nobody", since that’s the default from compile-time. The catch is that "nobody" can’t read your upsmon.conf, since by default it is installed so that only root can open it. This means you won’t be able to reload the configuration file, since it will be unavailable.

The solution is to create a new user just for upsmon, then make it run as that user. I suggest "nutmon", but you can use anything that isn’t already taken on your system. Just create a regular user with no special privileges and an impossible password.

Then, tell upsmon to run as that user, and make upsmon.conf readable by it. Your reloads will work, and your config file will stay secure.

This file should not be writable by the upsmon user, as it would be possible to exploit a hole, change the SHUTDOWNCMD to something malicious, then wait for upsmon to be restarted.

SHUTDOWNCMD command

upsmon runs this command when the system needs to be brought down. If it is a slave, it will do that immediately whenever the current overall power value drops below the MINSUPPLIES value above. When upsmon is a master, it will allow any slaves to log out before starting the local shutdown procedure.

Note that the command needs to be one element in the config file. If your shutdown command includes spaces, then put it in quotes to keep it together, i.e.:

```
SHUTDOWNCMD "/sbin/shutdown -h +0"
```

CERTPATH certificate file or database

When compiled with SSL support, you can enter the certificate path here. With NSS:

Certificates are stored in a dedicated database (splitted in 3 files). Specify the path of the database directory.

With OpenSSL:

Directory containing CA certificates in PEM format, used to verify the server certificate presented by the upsd server. The files each contain one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available.

CERTIDENT certificate name database password

When compiled with SSL support with NSS, you can specify the certificate name to retrieve from database to authenticate itself and the password required to access certificate related private key.

CERTHOST hostname certificate name certverify forcessl

When compiled with SSL support with NSS, you can specify security directive for each server you can contact. Each entry maps server name with the expected certificate name and flags indicating if the server certificate is verified and if the connection must be secure.

CERTVERIFY 0 | 1

When compiled with SSL support, make upsmon verify all connections with certificates. Without this, there is no guarantee that the upsd is the right host. Enabling this greatly reduces the risk of man-in-the-middle attacks. This effectively forces the use of SSL, so don’t use this unless all of your upsd hosts are ready for SSL and have their certificates in order.

When compiled with NSS support of SSL, can be overriden for host specified with a CERTHOST directive.

FORCESSL 0 | 1

When compiled with SSL, specify that a secured connection must be used to communicate with upsd. If you don’t use CERTVERIFY 1, then this will at least make sure that nobody can sniff your sessions without a large effort. Setting this will make upsmon drop connections if the remote upsd doesn’t support SSL, so don’t use it unless all of them have it running.

When compiled with NSS support of SSL, can be overriden for host specified with a CERTHOST directive.

## SEE ALSO
upsmon(8), upsd(8), nutupsdrv(8).

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upssched.conf

title: upssched.conf(5)

text:
# upssched.conf(5)

## NAME
upssched.conf - Configuration for upssched timer program

## DESCRIPTION
This file controls the operations of upssched(8), the timer-based helper program for upsmon(8).

## CONFIGURATION DIRECTIVES
CMDSCRIPT scriptname

Required. This must be above any AT lines. This script is used to invoke commands when your timers are triggered. It receives a single argument which is the name of the timer that caused it to trigger.

PIPEFN filename

Required. This sets the file name of the socket which will be used for interprocess communications. This should be in a directory where normal users can’t create the file, due to the possibility of symlinking and other evil.

Caution if you are running Solaris or similar, the permissions that upssched sets on this file are not enough to keep you safe. If your OS ignores the permissions on a FIFO, then you MUST put this in a protected directory!

Note by default, upsmon(8) will run upssched as whatever user you have defined with RUN_AS_USER in upsmon.conf(8). Make sure that user can create files and write to files in the path you use for PIPEFN and LOCKFN.

My recommendation: create a special directory for upssched, make it owned by your upsmon user, then use it for both.

The stock version of the upssched.conf ships with PIPEFN disabled to make you visit this portion of the documentation and think about how your system works before potentially opening a security hole.

LOCKFN filename

Required. upssched attempts to create this file in order to avoid a race condition when two events are dispatched from upsmon at nearly the same time. This file will only exist briefly. It must not be created by any other process. You should put this in the same directory as PIPEFN.

AT notifytype upsname command

Define a handler for a specific event notifytype on UPS upsname. upsname can be the special value * to apply this handler to every UPS. This will perform the command command when the notifytype and upsname match the current activity. Possible values for command are:

START-TIMER timername interval

Start a timer of interval seconds. When it triggers, it will pass the argument timername as an argument to your CMDSCRIPT. Example:

Start a timer that’ll execute when any UPS (*) has been gone for 10 seconds

```
AT COMMBAD * START-TIMER upsgone 10
```

CANCEL-TIMER timername [cmd]

Cancel a running timer called timername, if possible. If the timer has passed then pass the optional argument cmd to CMDSCRIPT. Example:

If a specific UPS (myups@localhost) comes back online, then stop the timer before it triggers

```
AT COMMOK myups@localhost CANCEL-TIMER upsgone
```

EXECUTE command

Immediately pass command as an argument to CMDSCRIPT. Example:

If any UPS (*) reverts to utility power, then execute ups-back-on-line via CMDSCRIPT.

```
AT ONLINE * EXECUTE ups-back-on-line
```

Note that any AT that matches both the notifytype and the upsname for the current event will be used.

For a complete list of notifytype possible values, refer to the section NOTIFY EVENTS in upsmon(8).

## SEE ALSO
upssched(8), upsmon(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


hosts.conf

package: nut-cgi

title: hosts.conf(5)

text:
# hosts.conf(5)

## NAME
hosts.conf - Access control for Network UPS Tools CGI programs

## DESCRIPTION
The CGI programs (upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)) use this file to determine if they are allowed to talk to a host. This keeps random visitors from using your web server to annoy others by creating outgoing connections.

## DIRECTIVES
MONITOR ups description

The ups element is in the form upsname[@hostname[:port]]. To allow connections to a UPS called "snoopy" on a system called "doghouse" that runs upsd on port 7877, it would look like this:

```
MONITOR snoopy@doghouse:7877 "Joe Cool"
```

The description must be one element, so if it has spaces, then it must be wrapped with quotes as shown above. The default hostname is "localhost".

## SEE ALSO
upsset.cgi(8), upsstats.cgi(8), upsimage.cgi(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upsset.conf

title: upsset.conf(5)

text:
# upsset.conf(5)

## NAME
upsset.conf - Configuration for Network UPS Tools upsset.cgi

## DESCRIPTION
This file only does one job—it lets you convince upsset.cgi(8) that your system’s CGI directory is secure. The program will not run until this file has been properly defined.

## SECURITY REQUIREMENTS
upsset.cgi(8) allows you to try login name and password combinations. There is no rate limiting, as the program shuts down between every request. Such is the nature of CGI programs.

Normally, attackers would not be able to access your upsd(8) server directly as it would be protected by the LISTEN directives in your upsd.conf(5) file, tcp-wrappers (if available when NUT was built), and hopefully local firewall settings in your OS.

upsset runs on your web server, so upsd will see it as a connection from a host on an internal network. It doesn’t know that the connection is actually coming from someone on the outside. This is why you must secure it.

On Apache, you can use the .htaccess file or put the directives in your httpd.conf. It looks something like this, assuming the .htaccess method:

```
<Files upsset.cgi>
deny from all
allow from your.network.addresses
</Files>
```

You will probably have to set "AllowOverride Limit" for this directory in your server-level configuration file as well.

If this doesn’t make sense, then stop reading and leave this program alone. It’s not something you absolutely need to have anyway.

Assuming you have all this done, and it actually works (test it!), then you may add the following directive to this file:

```
I_HAVE_SECURED_MY_CGI_DIRECTORY
```

If you lie to the program and someone beats on your upsd through your web server, don’t blame me.

## SEE ALSO
upsset.cgi(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upsstats.html

title: upsstats.html(5)

text:
# upsstats.html(5)

## NAME
upsstats.html - HTML template for Network UPS Tools upsstats

## DESCRIPTION
This file is used by upsstats.cgi(8) to generate status pages. Certain commands are recognized, and will be replaced with various status elements on the fly.

## FORMATTING
Commands can be placed anywhere on a line, but must start and end with @. Any extra characters before or after the commands will be passed through unchanged. It is allowed to use more than one command on a single line, as long as each command has its own start and end character. If you need to use the @ sign, use @ to prevent it from being treated as a start character.

## BLOCK CONTROL
Some commands begin blocks - sections of the template that will be included, excluded, or repeated depending on certain parameters.

### BLOCK CONTROL - ITERATION
@FOREACHUPS@

Starts a block that will be repeated for each MONITOR directive in the hosts.conf(5). This is how you can generate pages that monitor all of your systems simultaneously.

@ENDFOR@

Ends a FOREACHUPS block.

### BLOCK CONTROL - MATCHING SPECIFIC CASES
@IFSUPP var@*

Starts a block that will only be printed if the variable var is supported by the current UPS. This is generally used to suppress "not supported" messages by avoiding the label and variable call entirely.

@IFEQ var value@

Starts a block if the value returned from the variable var matches value.

@IFBETWEEN varlow varhigh varvalue@

Starts a block if the value returned by the variable varvalue is between the values returned by the variables varlow and varhigh.

@ELSE@

If the previous IF-command did not match, perform this instead.

@ENDIF@

Ends an IF/ELSE-block.

### BLOCK CONTROL - ADVANCED EXPRESSIONS
Even though the parser is pretty limited, it’s still possible to create rather advanced expressions. The key to this is the fact that multiple block control commands are AND:ed. This is illustrated with an example (more examples are available in upsstats.html).

```
@IFSUPP ambient.humidity@
@IFSUPP ambient.temperature@
This UPS knows both ambient temperature and humidity.
@ELSE@
@IFSUPP ambient.humidity@
This UPS only knows ambient humidity.
@ELSE@
@IFSUPP ambient.temperature@
This UPS only knows ambient temperature.
@ELSE@
This UPS knows nothing, how annoying.
@ENDIF@
```

## OTHER COMMANDS
@AMBTEMP@

Insert the ambient temperature in the current temperature scale.

@DATE format@

Insert the current date and time. The format string is passed to strftime, so almost anything is possible. See strftime(3) for possible values.

@DEGREES@

Insert the entity for degrees (°) and either C or F depending on the current temperature scale.

@HOST@

Insert the designation of the host being monitored, like myups@localhost.

@HOSTDESC@

Insert the hout’s description from hosts.conf(5).

@HOSTLINK@

Insert a link to upsstats.cgi with the "host" variable set to the current UPS. This is only useful within a FOREACHUPS block.

@IMG varname @

Insert an IMG SRC to upsimage.cgi(8) for one of these status variables: battery.charge

Battery charge - a percentage

battery.voltage

The charge on the battery in volts

input.frequency

Incoming utility frequency (Hz)

input.voltage

Incoming utility voltage

input.L1-L2.voltage

Incoming voltage, L1-L2 (3phase)

input.L2-L3.voltage

Incoming voltage, L2-L3 (3phase)

input.L3-L1.voltage

Incoming voltage, L3-L1 (3phase)

output.frequency

Outgoing utility frequency (Hz)

output.voltage

Outgoing voltage (from the UPS)

output.L1-L2.voltage

Outgoing voltage, L1-L2 (3phase)

output.L2-L3.voltage

Outgoing voltage, L2-L3 (3phase)

output.L3-L1.voltage

Outgoing voltage, L3-L1 (3phase)

output.L1.power.percent

UPS load, L1 (3phase)

output.L2.power.percent

UPS load, L2 (3phase)

output.L3.power.percent

UPS load, L3 (3phase)

ups.load

UPS load - percentage

ups.temperature

UPS temperature

extra is where you can put additional definitions. Right now the valid definitions are colors for various parts of the bars drawn by upsimage.cgi. Possible color names are:

back_col

background color

scale_num_col

scale number color

summary_col

summary color (number at the bottom)

ok_zone_maj_col

major scale color for the normal ("ok") zone

ok_zone_min_col

minor scale color for the normal ("ok") zone

neutral_zone_maj_col

major scale color for the neutral zone

neutral_zone_min_col

minor scale color for the neutral zone

warn_zone_maj_col

major scale color for the warning zone

warn_zone_min_col

minor scale color for the warning zone

bar_col

the color of the bar in the middle

All colors are hex triplets - 0xff0000 is red, 0x00ff00 is green, and 0x0000ff is blue.

Examples:

```
@IMG battery.charge@
@IMG battery.charge back_col=0xff00ff bar_col=0xaabbcc@
@IMG input.voltage ok_zone_maj_col=0x123456@
```

@REFRESH@

Insert the META header magic for refreshing the page if that variable has been set by the browser. This needs to be in the HEAD section of the page.

@STATUS@

Expand the abbreviations in the ups.status variable - OL becomes "On line", OB becomes "On battery", and so on.

@STATUSCOLOR@

Insert red, green, or yellow color triplets depending on the severity of the current UPS status. Normal operations are green, warnings like voltage trim/boost or "off" are yellow, and other events like being on battery or having a low battery are red.

@VAR varname@

Insert the current value of the status variable varname on the host being monitored, or "Not supported".

@RUNTIME@

Inserts the current runtime, in hh:mm:ss format.

@TEMPC@

Use the Celsius scale for temperature data (default).

@TEMPF@

Use the Fahrenheit scale for temperature data.

@UPSTEMP@

Insert the UPS temperature in the current scale.

@BATTTEMP@

Insert the battery temperature in the current scale.

@UTILITYCOLOR@

Obsoleted. Use IFBETWEEN instead (see example in upsstats.html).

@VERSION@

Insert the version number of the software.

## OTHER TEMPLATES
upsstats.cgi(8) will also open a file called upsstats-single.html if you call it with "host=" set in the URL. That file uses the same rules and techniques documented here.

## SEE ALSO
upsstats.cgi(8), upsimage.cgi(8)

### Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


ups.conf

package: nut-server

title: ups.conf(5)

summary: UPS definitions for Network UPS Tools

text:
# ups.conf(5)

## NAME
ups.conf - UPS definitions for Network UPS Tools

## DESCRIPTION
This file is read by the driver controller upsdrvctl(8), the UPS drivers that use the common core (see nutupsdrv(8), and upsd(8)). The file begins with global directives, and then each UPS has a section which contains a number of directives that set parameters for that UPS.

A UPS section begins with the name of the UPS in brackets, and continues until the next UPS name in brackets or until EOF. The name "default" is used internally in upsd, so you can’t use it in this file.

You must define the driver and port elements for each entry. Anything after that in a section is optional. A simple example might look like this:

```
[myups]

        driver = blazer_ser

        port = /dev/ttyS0

        desc = "Web server UPS"
```

A slightly more complicated version includes some extras for the hardware-specific part of the driver:

```
[bigups]

        driver = apcsmart

        port = /dev/cua00

        cable = 940-0095B

        sdtype = 2

        desc = "Database server UPS"
```

In this case, the apcsmart(8) driver will receive variables called "cable" and "sdtype" which have special meanings. See the man pages of your driver(s) to learn which variables are supported and what they do.

## GLOBAL DIRECTIVES
chroot

Optional. The driver will chroot(2) to this directory during initialization. This can be useful when securing systems.

driverpath

Optional. Path name of the directory in which the UPS driver executables reside. If you don’t specify this, the programs look in a built-in default directory, which is often /usr/local/ups/bin.

maxstartdelay

Optional. Same as the UPS field of the same name, but this is the default for UPSes that don’t have the field.

maxretry

Optional. Specify the number of attempts to start the driver(s), in case of failure, before giving up. A delay of retrydelay is inserted between each attempt. Caution should be taken when using this option, since it can impact the time taken by your system to start. The default is 1 attempt.

retrydelay

Optional. Specify the delay between each restart attempt of the driver(s), as specified by maxretry. Caution should be taken when using this option, since it can impact the time taken by your system to start. The default is 5 seconds.

pollinterval

Optional. The status of the UPS will be refreshed after a maximum delay which is controlled by this setting. This is normally 2 seconds. This may be useful if the driver is creating too much of a load on your system or network.

synchronous

Optional. The driver work by default in asynchronous mode (i.e synchronous=no). This means that all data are pushed by the driver on the communication socket to upsd (Unix socket on Unix, Named pipe on Windows) without waiting for these data to be actually consumed. With some HW, such as ePDUs, that can produce a lot of data, asynchronous mode may cause some congestion, resulting in the socket to be full, and the driver to appear as not connected. In such case, the driver will provide the following debug message:

```
write XX bytes to socket Y failed
```

By enabling the synchronous flag (value = yes), the driver will wait for data to be consumed by upsd, prior to publishing more. This can be enabled either globally or per driver.

The default is no (i.e. asynchronous mode) for backward compatibility of the driver behavior.

user

Optional. If started as root, the driver will setuid(2) to the user id associated with username.

## UPS FIELDS
driver

Required. This specifies which program will be monitoring this UPS. You need to specify the one that is compatible with your hardware. See nutupsdrv(8) for more information on drivers in general and pointers to the man pages of specific drivers.

port

Required. This is the serial port where the UPS is connected. On a Linux system, the first serial port usually is /dev/ttyS0. On FreeBSD and similar systems, it probably will be /dev/cuaa0.

sdorder

Optional. When you have multiple UPSes on your system, you usually need to turn them off in a certain order. upsdrvctl shuts down all the 0s, then the 1s, 2s, and so on. To exclude a UPS from the shutdown sequence, set this to -1. The default value for this parameter is 0.

desc

Optional. This allows you to set a brief description that upsd will provide to clients that ask for a list of connected equipment.

nolock

Optional. When you specify this, the driver skips the port locking routines every time it starts. This may allow other processes to seize the port if you start more than one accidentally. You should only use this if your system won’t work without it.

This may be needed on Mac OS X systems.

ignorelb

Optional. When you specify this, the driver ignores a low battery condition flag that is reported by the UPS (some devices will switch off almost immediately after setting this flag, or will report this as soons as the mains fails). Instead it will use either of the following conditions to determine when the battery is low:

```
battery.charge < battery.charge.low
battery.runtime < battery.runtime.low
```

The idea is to set the battery.charge.low and/or battery.runtime.low levels in ups.conf to a value that gives enough time to cleanly shutdown your system:

```
override.battery.charge.low = 30
override.battery.runtime.low = 180
```

In order for this to work, your UPS should be able to (reliably) report charge and/or runtime remaining on battery. Use with caution!

maxstartdelay

Optional. This can be set as a global variable above your first UPS definition and it can also be set in a UPS section. This value controls how long upsdrvctl will wait for the driver to finish starting. This keeps your system from getting stuck due to a broken driver or UPS. The default is 45 seconds.

synchronous

Optional. Same as the global directive of the same name, but this is for a specific device.

usb_set_altinterface[=altinterface]

Optional. Force the USB code to call usb_set_altinterface(0), as was done in NUT 2.7.2 and earlier. This should not be necessary, since the default for bAlternateSetting (as shown in lsusb) is zero on all USB devices seen to date. However, this redundant call to usb_set_altinterface() prevents certain UPSes from working on Mac OS X. If your UPS requires explicitly setting the alternate interface, include this flag, and email the nut-upsdev list with details about your UPS and operating system.

default.<variable>

Optional. Set a default value for <variable> which is used in case the UPS doesn’t provide a value, but will be overwritten if a value is available from the UPS:

```
default.input.voltage.nominal = 230
```

The above will report the nominal input voltage to be 230, unless the UPS tells us differently.

override.<variable>

Optional. Set a value for <value> that overrides any value that may be read from the UPS. Used for overriding values from the UPS that are clearly wrong (some devices report wrong values for battery voltage for instance):

```
override.battery.voltage.nominal = 12
```

Use with caution! This will only change the appearance of the variable to the outside world, internally in the UPS the original value is used.

All other fields are passed through to the hardware-specific part of the driver. See those manuals for the list of what is allowed.

## INTEGRATION
upsdrvctl(8) uses this file to start and stop the drivers.

The drivers themselves also obtain configuration data from this file. Each driver looks up its section and uses that to configure itself.

upsd(8) learns about which UPSes are installed on this system by reading this file. If this system is called "doghouse" and you have defined a UPS in your ups.conf called "snoopy", then you can monitor it from upsc(8) or similar as "snoopy@doghouse".

## SEE ALSO
upsd(8), nutupsdrv(8), upsdrvctl(8)

### Internet resources
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upsd.conf

title: upsd.conf(5)

text:
# upsd.conf(5)

## NAME
upsd.conf - Configuration for Network UPS Tools upsd

## DESCRIPTION
upsd uses this file to control access to the server and set some other miscellaneous configuration values. This file contains details on access controls, so keep it secure. Ideally, only the upsd process should be able to read it.

## CONFIGURATION DIRECTIVES
"MAXAGE seconds"

upsd usually allows a driver to stop responding for up to 15 seconds before declaring the data "stale". If your driver takes a very long time to process updates but is otherwise operational, you can use MAXAGE to make upsd wait longer. Most users should leave this at the default value.

"STATEPATH path"

Tell upsd to look for the driver state sockets in path rather than the default that was compiled into the program.

"LISTEN interface port"

Bind a listening port to the interface specified by its Internet address. This may be useful on hosts with multiple interfaces. You should not rely exclusively on this for security, as it can be subverted on many systems. Listen on TCP port port instead of the default value which was compiled into the code. This overrides any value you may have set with configure --with-port. If you don’t change it with configure or this value, upsd will listen on port 3493 for this interface.

Multiple LISTEN addresses may be specified. The default is to bind to 127.0.0.1 if no LISTEN addresses are specified (and ::1 if IPv6 support is compiled in).

```
LISTEN 127.0.0.1
LISTEN 192.168.50.1
LISTEN ::1
LISTEN 2001:0db8:1234:08d3:1319:8a2e:0370:7344
```

This parameter will only be read at startup. You’ll need to restart (rather than reload) upsd to apply any changes made here.

"MAXCONN connections"

This defaults to maximum number allowed on your system. Each UPS, each LISTEN address and each client count as one connection. If the server runs out of connections, it will no longer accept new incoming client connections. Only set this if you know exactly what you’re doing.

"CERTFILE certificate file"

When compiled with SSL support with OpenSSL backend, you can enter the certificate file here. The certificates must be in PEM format and must be sorted starting with the subject’s certificate (server certificate), followed by intermediate CA certificates (if applicable_ and the highest level (root) CA. It should end with the server key. See docs/security.txt or the Security chapter of NUT user manual for more information on the SSL support in NUT.

"CERTPATH certificate database"

When compiled with SSL support with NSS backend, you can enter the certificate path here. Certificates are stored in a dedicated database (splitted in 3 files). Specify the path of the database directory.

"CERTIDENT certificate name database password"

When compiled with SSL support with NSS backend, you can specify the certificate name to retrieve from database to authenticate itself and the password required to access certificate related private key.

"CERTREQUEST certificate request level"

When compiled with SSL support with NSS backend and client certificate validation (disabled by default, see docs/security.txt), you can specify if upsd requests or requires client’s' certificates. Possible values are :

•0 to not request to clients to provide any certificate

•1 to require to all clients a certificate

•2 to require to all clients a valid certificate

## SEE ALSO
upsd(8), nutupsdrv(8), upsd.users(5)

## INTERNET RESOURCES
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


upsd.users

title: upsd.users(5)

text:
# upsd.users(5)

## NAME
upsd.users - Administrative user definitions for NUT upsd

## DESCRIPTION
Administrative commands such as setting variables and the instant commands are powerful, and access to them needs to be restricted. This file defines who may access them, and what is available.

Each user gets its own section. The fields in that section set the parameters associated with that user’s privileges. The section begins with the name of the user in brackets, and continues until the next user name in brackets or EOF. These users are independent of /etc/passwd.

Here are some examples to get you started:

```
[admin]

        password = mypass

        actions = set

        actions = fsd

        instcmds = all
```

```
[pfy]

        password = duh

        instcmds = test.panel.start

        instcmds = test.panel.stop
```

```
[monmaster]

        password = blah

        upsmon master
```

```
[monslave]

        password = abcd

        upsmon slave
```

## FIELDS
password

Set the password for this user.

actions

Allow the user to do certain things with upsd. To specify multiple actions, use multiple instances of the actions field. Valid actions are: SET

change the value of certain variables in the UPS

FSD

set the forced shutdown flag in the UPS. This is equivalent to an "on battery + low battery" situation for the purposes of monitoring.

The list of actions is expected to grow in the future.

instcmds

Let a user initiate specific instant commands. Use "ALL" to grant all commands automatically. To specify multiple commands, use multiple instances of the instcmds field. For the full list of what your UPS supports, use "upscmd -l". The cmdvartab file supplied with the distribution contains a list of most of the known command names.

upsmon

Add the necessary actions for a upsmon process to work. This is either set to "master" or "slave". Do not attempt to assign actions to upsmon by hand, as you may miss something important. This method of designating a "upsmon user" was created so internal capabilities could be changed later on without breaking existing installations.

## SEE ALSO
upsd(8), upsd.conf(5)

## INTERNET RESOURCES
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/


nvram-wakeup.conf

package: nvram-wakeup

title: nvram-wakeup.conf(5)

text:
# nvram-wakeup.conf(5)

## NAME
nvram-wakeup.conf - the configuration file for NVRAM WakeUp.

## DESCRIPTION
This file can be passed to the program NVRAM WakeUp (see nvram-wakeup(8) for more information) via the --configfile option.

It might look as follows:

```
# nvram-wakeup.conf
#
#  This is an example configuration for MSI MS-6351
need_reboot = ON_ANY_CHANGE # All changes take effect
                            # after a reboot
addr_chk_h  = 0x30          # These are adresses of
addr_chk_l  = 0x31          # the checksum bytes
addr_stat   = 0x55          # Status byte
shift_stat  = 3             # The position of the
                            # status bit in the byte
addr_day    = 0x56          # Day and time
addr_hour   = 0x57
addr_min    = 0x58
addr_sec    = 0x59
```

## SYNTAX
Any empty line or a line containing only space characters is ignored.

Anything after and including a # character is treated as a comment and is ignored.

The options must have the form NAME = VALUE with or without spaces before NAME, after VALUE or around the equal sign. Valid options are described below.

The options may appear in any order. The same option must not appear twice.

## OPTIONS
bcd = (ON|OFF), default OFF

indicates if the board uses BCD notation for storing values.

BCD is the so called Binary Coded Decimal notation (actually, it is `packed BCD', in the plain BCD they waste whole byte per digit.) in this notation the decimal numbers 0..99 are stored using four bits for every digit, e.g. 24 would be stored as 0x24 (the 4 is stored in the lower four bits and the 2 is stored in the upper four bits).

addr_chk_h = (0x00|...|0x71), default: undefined

addr_chk_l = (0x00|...|0x71), default: undefined

addr_stat = (0x00|...|0x71), default: undefined

addr_mon = (0x00|...|0x71), default: undefined

addr_day = (0x00|...|0x71), default: undefined

addr_hour = (0x00|...|0x71), default: undefined

addr_min = (0x00|...|0x71), default: undefined

addr_sec = (0x00|...|0x71), default: undefined

Addresses of the bytes where the checksum (lower resp. higher bytes), status (enabled/disabled), month, day, hour, minute and second are stored in the nvram.

addr_chk_h, addr_chk_l and addr_stat must be defined. All other may stay undefined. That means, the board doesn't store them (e.g. because it stores that value in RTC alarm registers)

addr_chk_h2 = (0x00|...|0x71), default: undefined

addr_chk_l2 = (0x00|...|0x71), default: undefined

There are some boards which have two checksums. Since I haven't seen many of them yet, I don't know if they need special handling

addr_wdays = (0x00|...|0x71 ), default: undefined

The address of the byte containing a weekday vector. Currently, I know of only two boards, which store a weekday vector (Asus SP98-X and SP97-X).

rtc_time = (ON|OFF), default: OFF

indicates if we have to set the the RTC alarm time accordingly.

rtc_mon = (0x00|...|0x71|0x7F), default: undefined

rtc_day = (0x00|...|0x71|0x7F), default: undefined

similar to addr_mon/addr_day, but stored in BCD and not affecting the checksum. In most cases, the day is stored in the RTC register D (0x7F), but there are also some boards, which store it somewhere in the nvram (address <= 0x71).

If rtc_day is >= 0x72, you will need a kernel patch: in <kernel-src>/drivers/char/nvram.c change the line

\#define NVRAM_BYTES 128-RTC_FIRST_BYTE

to #define NVRAM_BYTES 128

in newer kernels (beginning with 2.4.20) it is the line #define NVRAM_BYTES (128-NVRAM_FIRST_BYTE)

which must be changed to #define NVRAM_BYTES 128

reset_mon = (ON|OFF), default: OFF

reset_day = (ON|OFF), default: OFF

on some boards we have to set the value of rtc_mon resp. rtc_day to 0 when disabling the wakeup feature.

nr_stat = 1 (just on/off)

nr_mon = 4 ( 0..12 )

nr_day = 5 ( 0..31 )

nr_rtc_mon = 5 (0x00...0x12)

nr_rtc_day = 6 (0x00...0x31)

nr_wdays = 7 ( 1 per day )

nr_hour = 5 ( 0..23 )

nr_min = 6 ( 0..59 )

nr_sec = 6 ( 0..59 )

Number of bits needed for the status, month, day, rtc_day, weekday vector, hour, minute and second. These values are a priori motherboard independent but depend on the BCD/non-BCD notation.

shift_stat = (0|...|7), default: 0

shift_mon = (0|...|4), default: 0

shift_day = (0|...|3), default: 0

shift_wdays = (0|...|1), default: 0

shift_hour = (0|...|3), default: 0

shift_min = (0|...|2), default: 0

shift_sec = (0|...|2), default: 0

Indicates, by how many bits the value is shifted to the left in the byte, e.g. the value of the day (5 bits) could be stored in the bits marked with an "x" of a byte:

000xxxxx -> shift_day = 0

00xxxxx0 -> shift_day = 1

0xxxxx00 -> shift_day = 2

xxxxx000 -> shift_day = 3

need_reboot = (OFF|ON_STAT|ON_SEC|ON_MIN|ON_HOUR

|ON_DAY|ON_MON|ON_WDAYS|ON_ANY_CHANGE|...),

default: OFF

Here "..." means any or-ed combination of multiple ON_XXX values.

Some boards need a reboot for changes in nvram to take effect. Some of them need a reboot after _any_ change, some of them only after the status bit was changed. Anyway, now we are able to define when a board needs a reboot:

OFF

means, the board never needs it

ON_ANY_CHANGE

means, the board needs it after _any_ change on nvram.

ON_STAT

means, reboot only if the status bit is changed

ON_STAT|ON_SEC

means, reboot whenever the status or the second are changed.

The idea behind this is if nvram-wakeup decides that we need to reboot, it will exit with exit status 1 (instead of 0). So the script which runs nvram-wakeup could react on this. We also print it to stderr, so if nvram-wakeup is run directly on the command line, the user could react appropriately.

upper_method = (OFF|INTEL|DS1685|VT82Cxxx|VT8235_37), default: OFF

indicates if upper nvram must be used and if yes, which method to use to access it. Note that upper nvram can only be read if --directisa parameter is specified. Possible values:

OFF

upper nvram disabled (default)

INTEL

access upper nvram by a method used by most (if not all) Intel chipsets with ICH, ICH2, C-ICH, ... (datasheets at http://intel.com/design/chipsets/datashts/)

DS1685

access upper nvram by a method used by the Dallas Semiconductor DS1685/DS1687 chips. (datasheet at http://www.farnell.com/datasheets/4182.pdf)

VT82Cxxx

access upper nvram by a method used by VIA's VT82C686A "Super South" South Bridge. Reported to work with VT82C686A, VT82C686B, VT82C596, nVidia nForce2, ATI RADEON 9100 IGP (= RS300), AMD-8111. (datasheet at http://www.viatech.com/pdf/productinfo/686a.pdf)

(datasheet at http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/24674.pdf)

VT8235_37

access upper nvram by a method used by VIA's VT8235/37 South Bridges. Reported to work with VT8233 as well. (no official source)

chk_method = (DELL|FSC), default: undefined

indicates which algorithm for calculation of the checksum must be used. Possible values:

undefined

Majority of mainboards use the same algorithm (just addition of values). This algorithm is used if no chk_method option is specified.

DELL

This method is used by many Dell mainboards (addition of negative values).

FSC

Fujitsu-Siemens uses yet another algorithm. I don't know it and they consider it as a company secret. Thus this method is not implemented.

## OBSCURE OPTIONS
rtc_mon_0_is_c0 = (ON|OFF), default: OFF

rtc_day_0_is_c0 = (ON|OFF), default: OFF

on some boards we have to store the value 0xC0 instead of 0 in rtc_mon resp. rtc_day. If you use one of this two options, don't forget to set nr_rtc_mon resp. nr_rtc_day to 8.

day_hack = (1|...|4), default: undefined

on some boards the value of addr_day is split over the day and the status byte. In those cases the lower day_hack bits of the day value are stored in the highest bits of the status byte and the rest is stored in the day byte.

day_no_bcd = (ON|OFF), default: OFF

on some boards the value of addr_day is not stored in BCD, although everything else is. This option has no effect is the option bcd is not enabled.

## SEE ALSO
nvram-wakeup(8)

## HOMEPAGE
http://sf.net/projects/nvram-wakeup/

## AUTHOR
Written by Sergei Haller <Sergei.Haller@math.uni-giessen.de>.

## REPORTING BUGS
Report bugs at the bug tracking system (see HOMEPAGE) or on the mailing list nvram-wakeup-devel@lists.sourceforge.net

## COPYRIGHT
Copyright © 2001-2004 Sergei Haller.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


META

package: ocaml-findlib

title: META(5)

text:
# META(5)

## NAME
META - [File that specifies metainformation of OCaml packages]

## GRAMMAR

```
         metafile ::= entry*

            entry ::= assignment | addition | subpackage

       subpackage ::= "package" pkgname '(' metafile ')'

       assignment ::= variable_name [ formal_predicates ] '='  value

         addition ::= variable_name [ formal_predicates ] '+=' value

formal_predicates ::= '(' formal_predicate { ',' formal_predicate } ')'

    variable_name ::= name

 formal_predicate ::= name | '-' name

             name ::= [ 'A'-'Z' 'a'-'z' '0'-'9' '_' '.' ]+

          pkgname ::= '"' (character but not '.')* '"'

            value ::= '"' character* '"'
```

## DESCRIPTION
If a package directory contains a file with the fixed name "META" it is interpreted as described here. The file is a sequence of entries following the given grammar; every entry defines a variable under a certain condition given by the list of formal predicates, or it introduces a subpackage.

There is a list of predefined variables and a list of standard predicates. These variables define: required packages, description, version information, directories, archive files, and linker options. The predicates denote circumstances of the application of the variables: whether the bytecode or the native compiler is used, if there is a toploop compiled in, details of multi-threading execution, details of profiling.

## DETAILS OF THE FILE FORMAT
The file consists of a sequence of entries which must be formed as the grammar prescribes. The lexical tokens are names, values, and interpunctuation like '(', ',' and so on. Note that linefeeds do not play a special role, i.e. an entry definition may be given in more than one line, or several definitions may occur on a single line. There may be comments which begin with '#' and run until the end of the line.

Names are sequences of the characters A-Z, a-z, 0-9, or _. Names containing capital letters and names beginning with digits are allowed but not recommended.

Values are enclosed between double quotes. Values may contain any character. The characters " and \ must be preceded by backslashes.

Package names must not contain the '.' character because it is used as delimiter of compound names.

## MAIN PACKAGES AND SUBPACKAGES
The outermost variable assignments and additions belong to the main package. The name of the main package is not defined within META; it is either the name of the directory containing META or the suffix of the META file (if the name of the META file is formed like META.name).

The keyword package starts the definition of a subpackage. There must not be two such definitions with the same name. Within the parantheses, the variable assignments and additions refer to the subpackage. It is allowed that a subpackage contains further subpackages.

The package name following package is the local name relative to the main package, i.e. the name of the main package is not mentioned. At all other places, however, the subpackage must be prefixed by the name of the containing package, separated by a '.'.

Subpackages are independent of the containing package, except that the subpackage points to the same installation directory as the containing package (i.e. the location of the installation directory is inherited from the containing package).

## SEMANTICS OF VARIABLE DEFINITIONS
In order to determine the value of a variable, first all assignments are inspected, and the most specific assignment is taken (if there is none, the empty string will be taken as value). In a second step, all additions are gone through one after the other in the order they occur in the file, and the values of all matching additions are appended to the current value. In the following, it is further clarified which assignment is the most specific, which additions actually match, and how the details of the value addition look like.

The most specific assignment is selected upon a set of actual predicates, i.e. the set of predicates that are assumed to be true. The predicates occuring in the definitions of assignments and additions are called formal predicates. They may be positive or negative; the latter are prepended by a '-' sign. In order to determine the value after the evaluation of the assignments, the following rules apply:

An assignment can only be used if all positive formal predicates are included in the set of actual predicates, and if all negative formal predicates are not included in the set of actual predicates. Such an assignment is called applicable. If there is no such assignment, the variable will have no value.

If there is more than one applicable assignment, the definition with the biggest number of formal predicates is selected.

If there is still more than one applicable assignment, both applicable and with a maximum number of formal predicates, the definition that is defined first is selected.

An addition is matching when all positive formal predicates are included in the set of actual predicates, and all negative formal predicates are not included.

The value of an addition is appended to the current value with implicit white space as separator.

## VARIABLES
There is a set of variables with predefined meaning:

The variable "directory" redefines the location of the package directory. Normally, the META file is the first file read in the package directory, and before any other file is read, the "directory" variable is evaluated in order to see if the package directory must be changed. The value of the "directory" variable is determined with an empty set of actual predicates. The value must be either: an absolute path name of the alternate directory, or a path name relative to the stdlib directory of OCaml (written "+path"), or a normal relative path name (without special syntax). In the latter case, the interpretation depends on whether it is contained in a main or sub package, and whether the standard repository layout or the alternate layout is in effect (see site-lib for these terms). For a main package in standard layout the base directory is the directory physically containing the META file, and the relative path is interpreted for this base directory. For a main package in alternate layout the base directory is the directory physically containing the META.pkg files. The base directory for subpackages is the package directory of the containing package. (In the case that a subpackage definition does not have a "directory" setting, the subpackage simply inherits the package directory of the containing package. By writing a "directory" directive one can change this location again.)

The variable "requires" specifies the list of required packages. The names of the packages must be separated by white space and/or commas. The names must be fully qualified (i.e. when they refer to a subpackage, the names of all containing packages must be prepended, separated by '.').

The variable "description" may include a short description of the package (displayed by ocamlfind list).

The variable "version" specifies the version string.

The variable "archive" specifies the list of archive files. These files should be given either as (1) plain names without any directory information; they are only searched in the package directory. (2) Or they have the form "+path" in which case the files are looked up relative to the standard library. (3) Or they have the form "@name/file" in which case the files are looked up in the package directory of another package. (4) Or they are given as absolute paths. The names of the files must be separated by white space and/or commas. In the preprocessor stage, the archive files are passed as extensions to the preprocessor (camlp4) call. In the linker stage (-linkpkg), the archive files are linked. In the compiler stage, the archive files are ignored.

Note that "archive" should only be used for archive files that are intended to be included in executables or loaded into toploops. For modules loaded at runtime there is the separate variable "plugin".

The variable "plugin" specifies the plugin archives of the package. These can be dynamically loaded with the Fl_dynload module. The plugin archives can have ".cmo", ".cma", or ".cmxs" suffix.

The variable "linkopts" specifies additional linker options.

The variable "error" can be used to signal error conditions. When this variable is applicable, the ocaml compilers are stopped, and an error message is printed. The message is the value of the variable.

The variable "warning" can be used to signal warnings. When this variable is applicable, the warning is printed, but the compilation continues. The message is the value of the variable.

The variable "exists_if" can be used to disable subpackages. The value of "exists_if" is a file; the subpackage is hidden if this file does not exist. You can also enumerate several files, and the subpackage is hidden if none of the files exist.

The variable "ppx" is a command that is added to the compiler invocation via the -ppx option (available since OCaml-4.01). If the command is relative to the current directory (e.g. ./cmd), the command is expected in the package directory. The special forms as defined for "archive" are also available (e.g. @otherpkg/cmd). Additional arguments can be specified on the ocamlfind command line with the -ppxopt option or the "ppxopt" variable.

The variable "ppxopt" is a set of options that are added to the ppx rewriter invocation. The contents of the variable consists of one or several whitespace-separated parts. Every part consists of several comma-separated subparts; the first subpart indicates the package that contains the ppx rewriter invocation, the rest contain the options to be appended. If the option is a path relative to the current directory (e.g. ./foo.cma), the path is expanded relative to the package directory. The special forms as defined for "archive" are also available (e.g. @otherpkg/foo.cma).

It is possible to define additional variables but there is currently no software interpreting them.

## PREDICATES
There is a list of standard predicates:

The "byte" predicate means that the bytecode compiler is used.

The "native" predicate means that the native compiler is used.

The "toploop" predicate means that the toploop is available in the linked program. It is only set when the toploop is running, not when the toploop is generated.

The "create_toploop" predicate means that a toploop is created (using ocamlmktop).

The "mt" predicate means that the program is multi-threaded.

The "mt_posix" predicate means that in the case "mt" is set, too, the POSIX libraries are used to implement threads.

The "mt_vm" predicate means that in the case "mt" is set, too, the VM-based libraries are used to implement threads.

The "gprof" predicate means that in the case "native" is set, too, the program is compiled for profiling

The "autolink" predicate means that ocamlc can/will perform automatic linking.

The "preprocessor" predicate means that the META variables are scanned for preprocessor options.

The "syntax" predicate means that the -syntax option is present on the command line.

Legacy: The "plugin" predicate could be used in some versions of findlib to select cmxs archives instead of cmxa archives. This use is still possible but discouraged.

In addition to these predicates, there are package predicates for every package that is finally selected. Of course, this kind of predicate must not be used to select "directory" and "requires" variables, but for the other variables they are perfectly valid. The package predicates have the form "pkg_" plus the name of the package (fully qualified).


findlib.conf

title: findlib.conf(5)

text:
# findlib.conf(5)

## NAME
findlib.conf - [Configuration of findlib/ocamlfind]

## GENERAL
There are three possibilities to configure the findlib library:

Build time:

Before findlib is compiled, a "configure" script is invoked to figure out the settings that are most likely to work on the system. Most settings are simply entered into text files and can easily be changed after installation. The following properties cannot be changed later because they are compiled into the resulting binaries:

The default location of the configuration file findlib.conf. However, you can set a different location by the environment variable OCAMLFIND_CONF.

Whether the installed O'Caml version supports autolinking or not.

Configuration file findlib.conf:

An initial version of this file is generated by the configure script, but you are free to modify it later. Most important, this file contains the system-wide search path used to look up packages, and the default location where to install new packages. All files with the suffix ".conf" found in the directory findlib.conf.d are also scanned for parameters.

Environment variables:

The settings of findlib.conf can be overridden by environment variables.

Last but not least, several settings can also be passed as command-line options, or by invoking the function Findlib.init.

## findlib.conf
The directory containing findlib.conf is determined at build time (by running the configure script), the fallback default is /usr/local/etc. You can set a different location by changing the environment variable OCAMLFIND_CONF which must contain the absolute path of findlib.conf.

The file has the same syntax as META, i.e. it consists of a number of lines with the format

```
variable
 = "
value
"
```

Here is the list of allowed variables:

path

The search path for META files/package directories. The variable enumerates directories which are separated by colons (Windows: semicolons), and these directories are tried in turn to find a certain package. More exactly, if d is such a directory and p the searched package, the search algorithm will first check whether d/p/META exists. In this case, this META file is taken, and d/p is the package directory. Second, the algorithm tries d/META.p, but the package directory must be specified in this META.p file by a directory directive. Note that the first found META file is taken, so the order of the directories in the search path counts.

This variable is required.

Example:

```
path = "/usr/local/lib/ocaml/site-lib:/usr/lib/ocaml/site-lib"
```

destdir

This variable determines the location where ocamlfind install puts the packages by default: If d is this directory, and p the package to install, a new subdirectory d/p will be created containing all the files of the package. Example:

```
destdir = "/usr/local/lib/ocaml/site-lib"
```

This variable is required.

metadir

If set, the command ocamlfind install will put the META files of packages into this directory (files are named META.p where p=package name); otherwise the META files are put into the package directories like any other file. Example:

```
metadir = "/var/lib/findlib/metaregistry"
```

This variable is optional. It is not used by default.

ocamlc, ocamlopt, ocamlcp, ocamlmktop, ocamldoc, ocamldep, ocamlbrowser

If you want to call other executables than "ocamlc", "ocamlopt", "ocamlcp", "ocamlmktop", "ocamldoc", "ocamldep", and "ocamlbrowser", you can set the names of the executables here. The command ocamlfind looks into these four variables to determine the names of the compilers to call. Example:

```
ocamlc     = "ocamlc.opt"

ocamlopt   = "ocamlopt.opt"

ocamlcp    = "ocamlcp.opt"

ocamlmktop = "ocamlmktop.opt"
```

This variable is optional. It is not used by default.

stdlib

This variable determines the location of the standard library. This must be the same directory for which the O'Caml compilers are configured. This variable is optional. It is not recommend to set this variable unless you know what you are doing!

ldconf

This variable determines the location of the ld.conf file. This must be the same file the O'Caml compilers read in; it is updated by ocamlfind when installing and removing packages. You can set this variable to the special value "ignore" to disable the automatic modification of the ld.conf file. If not set, the ld.conf file is assumed to reside in the O'Caml standard library directory.

This variable is optional. It is not recommended to set this variable unless you know what you are doing!

Toolchains: It is possible to have variants of the original configuration. These variants are called "toolchains" because they are intended to select different compilers, e.g. patched compilers. In order to set a variable for a certain toolchain, use the syntax

```
variable
(
toolchain
) = "
value
"
```

For example:

```
ocamlc(mypatch) = "ocamlc-mypatch"
```

When the toolchain "mypatch" is selected, this compiler will be used instead of the standard one. In order to switch to a certain toolchain, use the -toolchain option of ocamlfind.

## Environment
A number of environment variables modifies the behaviour of findlib/ocamlfind:

OCAMLFIND_CONF

This variable overrides the location of the configuration file findlib.conf. It must contain the absolute path name of this file.

OCAMLFIND_TOOLCHAIN

This variable sets the currently selected toolchain when a -toolchain option is not passed on the command line.

OCAMLPATH

This variable may contain an additional search path for package directories. It is treated as if the directories were prepended to the configuration variable path.

OCAMLFIND_DESTDIR

This variable overrides the configuration variable destdir.

OCAMLFIND_METADIR

This variable overrides the configuration variable metadir.

OCAMLFIND_COMMANDS

This variable overrides the configuration variables ocamlc, ocamlopt, ocamlcp, ocamlmktop, ocamldoc, ocamldep, and/or ocamlbrowser. Its value must conform to the syntax

```
ocamlc=
name
 ocamlopt=
name
 ocamlcp=
name
 ocamlmktop=
name
 ocamldoc=
name
 ocamldep=
name
 ocamlbrowser=
name
```

Example:

```
ocamlc=ocamlc-3.00 ocamlopt=ocamlopt-3.00 ocamlcp=ocamlcp-3.00 ocamlmktop=ocamlmktop-3.00
```

CAMLLIB or OCAMLLIB

This variable overrides the configuration variable stdlib.

OCAMLFIND_LDCONF

This variable overrides the configuration variable ldconf.

OCAMLFIND_IGNORE_DUPS_IN

This variable instructs findlib not to emit warnings that packages or module occur several times. The variable must be set to the directory where the packages reside that are to be ignored for this warning.


site-lib

title: site-lib(5)

text:
# site-lib(5)

## NAME
site-lib - [Location of package directories]

## STANDARD LAYOUT

```
...somewhere in the filesystem hierarchy...

   |

   \

     site-lib

     |

     +- (optional) stublibs

     +- (optional) postinstall

     +- (optional) postremove

     |

     +-
package1

     |  |

     |  +- META

     |  +-
archive files

     |  +-
interface definitions

     |

     +-
package2

     +

     :

     :

     \

packageN
```

## DESCRIPTION
Every installation of "findlib" has a default location for package directories, which is normally a directory called "site-lib". The location can be set by the configuration variables path (used to look up packages), and destdir (used to install new packages); see findlib.conf.

The name of a package is the name of the package directory. For example, if destdir=/usr/local/lib/ocaml/site-lib, the package p will be installed in the subdirectory /usr/local/lib/ocaml/site-lib/p. This subdirectory must contain the META file and all other files belonging to the package. Package names must not contain the '.' character.

The variable destdir specifies the directory for new packages. You can only have one such directory at a time; but of course you can change this directory in findlib.conf. The command ocamlfind install puts new packages into this directory; it is recommended to use this command for installation because it ensures that the directory layout is right.

For searching packages, findlib uses (only) the variable path which may name several locations to look at.

For systems with DLL support another directory may exist: stublibs. If present, findlib will install DLLs into this directory that is shared by all packages at the same site-lib location. Findlib remembers which DLL belongs to which package by special files with the suffix ".owner"; e.g. for the DLL "dllpcre.so" there is another file "dllpcre.so.owner" containing the string "pcre", so findlib knows that the package "pcre" owns this DLL. It is not possible that a DLL is owned by several packages.

If the stublibs directory does not exist, DLLs are installed regularly in the package directories like any other file.

For special needs, a postinstall and/or a postremove script may be installed in the site-lib directory. These scripts are invoked after installation or removal of a package, respectively.

## ALTERNATE LAYOUT

```
...somewhere in the filesystem hierarchy...

   |

   \

     site-lib

     |

     +- (optional) stublibs

     +- (optional) postinstall

     +- (optional) postremove

     |

     +-
package1

     |  |

     |  +-
archive files

     |  +-
interface definitions

     |

     +-
package2

     +

     :

     :

     \

  :
packageN

  |

  \

    metaregistry

    |

    +- META.package1

    +- META.package2

    +

    :

    \

       META.packageN
```

This is an alternate directory layout collecting all META files in one directory. You can configure this layout by setting path to the absolute location of metaregistry. Findlib recognizes that there are META files in this directory and uses them; it is not necessary to include site-lib into the path.

In order to work, the META files must contain a directory directive pointing to the corresponding package directory that resides below site-lib.

The command ocamlfind install copes with this layout, too. The variable destdir must contain the absolute location of site-lib, and the variable metadir must contain the absolute location of metaregistry. Note that ocamlfind install automatically adds a directory directive to the META file, so you need not do it manually.


ocaml-gettext

package: ocaml-gettext-devel

title: ocaml-gettext(5)

text:
# ocaml-gettext(5)

## NAME
ocaml-gettext - common options to manage internationalisation in OCaml program through ocaml-gettext library.

## SYNOPSIS
[--gettext-failsafe [{ignore} | {inform-stderr} | {raise-exception}]] [--gettext-disable] [--gettext-domain-dir {textdomain} {dir}] [--gettext-dir {dir}] [--gettext-language {language}] [--gettext-codeset {codeset}]

## DESCRIPTION
This section describes briefly the common options provided by programs using ocaml-gettext library.

--gettext-failsafe ignore

Defines the behaviour of ocaml-gettext regarding any error that could be encountered during the processing of string translation. ignore is the default behaviour. The string returned is the original string untranslated. This behaviour is consistent and allows to have a usable output, even if it is not perfect.

--gettext-failsafe inform-stderr

Same behaviour as ignore, except that a message is printed on stderr,

--gettext-failsafe raise-exception

Stops the program by raising an exception when an error is encountered.

--gettext-disable

Disables any translation made by ocaml-gettext. All translations return the original string untranslated.

--gettext-domain-dir textdomain dir

Defines a dir to search for a specific domain. This could be useful if MO files are stored in a non standard directory.

--gettext-dir dir

Adds a directory to search for MO files.

--gettext-language language

Sets the language to use in ocaml-gettext library. The language should be POSIX compliant. The language should follow the following convention: lang[_territory][.charset][@modifier]. The lang and territory should be two letters ISO code. Charset should be a valid ISO character set (at least recognised by the underlying charset recoding routine). For example, valid languages are: fr_FR.ISO-8859-1@euro, de_DE.UTF-8.

--gettext-codeset codeset

Sets the codeset for output.

Users should be aware that these command line options, apply only for strings after the initialisation of the library. This means that if the options initially guessed by ocaml-gettext don't match the command line provided, there should be some untranslated string, because these strings are translated before parsing options. This is particularly true for the usage message itself (--help): even if the strings are translated, they are translated before setting the correct option.

Some options (--gettext-codeset for example) are overrided internally for particular use. It should be required to always translate strings to UTF-8 in graphical user interface (because GTK2 requires it).

## AUTHORS
Sylvain Le Gall.


lambda-term-inputrc

package: ocaml-lambda-term

title: lambda-term-inputrc(5)

text:
# lambda-term-inputrc(5)

## NAME
lambda-term-inputrc - Key bindings for lambda-term applications

## SYNOPSIS
~/.config/.lambda-term-inputrc

## DESCRIPTION
This manual page describes the format of the ~/.config/.lambda-term-inputrc file. This file is a text file which associates editing actions to key sequences. Comments start with a '#' character and empty lines are ignored.

Bindings are of the form:

<key-sequence>: <actions>

Where <key-sequence> is a sequence of keys in the emacs format. For example Control+w is written "C-w", Control+Meta+x followed by "e" is written "C-M-x e". <actions> is a list of editing actions separeted by commas. The list of all available actions with a short description can be obtained by running the command lambda-term-actions(1) in a terminal.

The file is divided in two section, the [edit] section and the [read-line] section. The first one is for key bindings that apply everyhere and the second for key bindings that apply only in read-line.

Here is an example of bindings:

[read-line]

C-w: kill-prev-word

M-!: play-macro

In addition to letters and symbols the following keys can be used:

* enter

* escape

* tab

* up

* down

* left

* right

* f1

* f2

* f3

* f4

* f5

* f6

* f7

* f8

* f9

* f10

* f11

* f12

* next

* prev

* home

* end

* insert

* delete

* backspace

Note that lambda-term accept only ascii characters in the configuration file, to use other unicode character you must use the notation U+<code> where <code> is the code of the character in hexadecimal.

## FILES
~/.config/.lambda-term-inputrc

## EXAMPLE
[edit]

C-e: play-macro

[read-line]

C-left: complete-bar-prev

C-right: complete-bar-next

## AUTHOR
Jérémie Dimino <jeremie@dimino.org>

## SEE ALSO
lambda-term-actions(1).


title: o2cb.sysconfig(5)

text:
# o2cb.sysconfig(5)

## NAME
/etc/sysconfig/o2cb - Cluster configuration file for the o2cb cluster stack.

## SYNOPSIS
The configuration file /etc/sysconfig/o2cb stores the active cluster stack, its name and the various cluster timeouts for the o2cb cluster stack.

## DESCRIPTION
This file can be populated using the o2cb init script. An example of the same is illustrated in the examples section.

The list of configurable parameters in this file are:

O2CB_STACK

Name of the cluster stack. The possible values are o2cb, pcmk and cman. o2cb is the default cluster stack of the OCFS2 file system. pcmk (Pacemaker) and cman (rgmanager) are the two other cluster stacks that are supported by the same file system.

O2CB_BOOTCLUSTER

Name of the active cluster. While /etc/ocfs2/cluster.conf can hold descriptions of multiple clusters, only one can be active at any one time. The name of that active cluster is specified here. The name itself can be up to 16 alphanumeric characters [0-9A-Za-z] with no special characters.

The remaining configurable parameters (cluster timeouts) are only relevant for the o2cb cluster stack. These cluster timeouts are used by the o2cb cluster stack to determine whether a node is dead or alive. The default timeouts are just a guide and may need to be tweaked depending on the hardware the software is running on.

The various cluster timeouts for the o2cb cluster stack are:

O2CB_HEARTBEAT_THRESHOLD

The disk heartbeat timeout is the number of two second iterations before a node is considered dead. The exact formula used to convert the timeout in seconds to the number of iterations is as follows:

O2CB_HEARTBEAT_THRESHOLD = (((timeout in seconds) / 2) + 1)

For example, to specify a 60 sec timeout, set it to 31. For 120 secs, set it to 61. The default for this timeout is 60 secs (O2CB_HEARTBEAT_THRESHOLD = 31).

While it defaults to 60 secs, multipath users typically set it to 120 secs.

O2CB_IDLE_TIMEOUT_MS

The network idle timeout specifies the time in milliseconds before a network connection is considered dead. While it defaults to 30000 ms, network bonding users typically set it to 60000 ms.

O2CB_KEEPALIVE_DELAY_MS

The network keepalive specifies the maximum delay in milliseconds before a keepalive packet is sent to another node to check whether it is alive or not. It defaults to 2000 ms.

O2CB_RECONNECT_DELAY_MS

The network reconnect specifies the minimum delay in milliseconds between repeated connect attempts. It defaults to 2000 ms.

## EXAMPLE
The example below illustrates populating the o2cb sysconfig file using the o2cb init script.

```
$ service o2cb configure
Configuring the O2CB driver.
This will configure the on-boot properties of the O2CB driver.
The following questions will determine whether the driver is loaded on
boot.  The current values will be shown in brackets ('[]').  Hitting
<ENTER> without typing an answer will keep that current value.  Ctrl-C
will abort.
Load O2CB driver on boot (y/n) [n]: y
Cluster stack backing O2CB [o2cb]:
Cluster to start on boot (Enter "none" to clear) [ocfs2]: webcluster
Specify heartbeat dead threshold (>=7) [31]: 62
Specify network idle timeout in ms (>=5000) [30000]: 60000
Specify network keepalive delay in ms (>=1000) [2000]:
Specify network reconnect delay in ms (>=2000) [2000]:
Writing O2CB configuration: OK
$ cat /etc/sysconfig/o2cb
#
# This is a configuration file for automatic startup of the O2CB
# driver.  It is generated by running /etc/init.d/o2cb configure.
# On Debian based systems the preferred method is running
# 'dpkg-reconfigure ocfs2-tools'.
#
# O2CB_ENABLED: 'true' means to load the driver on boot.
O2CB_ENABLED=true
# O2CB_STACK: The name of the cluster stack backing O2CB.
O2CB_STACK=o2cb
# O2CB_BOOTCLUSTER: If not empty, the name of a cluster to start.
O2CB_BOOTCLUSTER=webcluster
# O2CB_HEARTBEAT_THRESHOLD: Iterations before a node is considered dead.
O2CB_HEARTBEAT_THRESHOLD=62
# O2CB_IDLE_TIMEOUT_MS: Time in ms before a network connection is considered dead.
O2CB_IDLE_TIMEOUT_MS=60000
# O2CB_KEEPALIVE_DELAY_MS: Max time in ms before a keepalive packet is sent
O2CB_KEEPALIVE_DELAY_MS=2000
# O2CB_RECONNECT_DELAY_MS: Min time in ms between connection attempts
O2CB_RECONNECT_DELAY_MS=2000
```

## SEE ALSO
o2cb(7) o2cb(8) ocfs2.cluster.conf(5)

## AUTHORS
Oracle Corporation

## COPYRIGHT
Copyright © 2004, 2012 Oracle. All rights reserved.


title: ocfs2.cluster.conf(5)

text:
# ocfs2.cluster.conf(5)

## NAME
/etc/ocfs2/cluster.conf - Cluster configuration file for the o2cb cluster stack.

## SYNOPSIS
The cluster layout of the o2cb cluster stack is specified in /etc/ocfs2/cluster.conf. It lists the name of the cluster, the nodes comprising that cluster and its heartbeat regions. The cluster stack expects this file to be the same on all nodes in that cluster.

This file should be populated using the o2cb(8) cluster configuration utility. A sample of the same is shown in the example section.

## DESCRIPTION
The configuration file is divided into three types of stanzas, each with a list of parameters and values. The three stanza types are cluster, node and heartbeat. While a configuration file can store definitions of multiple clusters, the o2cb cluster stack allows only one cluster to be active at any one time. The name of this active cluster is stored in /etc/sysconfig/o2cb [o2cb.sysconfig(5)].

The cluster stanza specifies the name of the cluster, number of nodes and the heartbeat mode. The cluster name can include up to 16 alphanumeric characters [0-9A-Za-z]. No special characters are allowed.

Parameters

Description

node_count

Number of nodes in the cluster

heartbeat_mode

local or global heartbeat

name

Cluster name (up to 16 alphanumeric chars [0-9A-Za-z])

The node stanza specifies the node name that is part of the cluster alongwith its IPv4 address, port and node number. The node name must match the hostname. The domain name is not required. For example, appserver1.company.com can be appserver1. The IPv4 address need not be the one associated with that hostname. As in, any valid IPv4 address on that node can be used. The o2cb cluster stack will not attempt to match the node name (hostname) with the specified IPv4 address. A low-latency private interconnect address is recommended for best performance.

Parameters

Description

ip_port

IPv4 port

ip_address

IPv4 address (private interconnect recommended)

number

Node number (0 - 254)

name

Node name (hostname without the domain name)

cluster

Cluster name (should match the name in the cluster stanza)

The heartbeat stanza specifies the global heartbeat region UUIDs. A cluster can have up to 32 heartbeat regions. This is an optional stanza and is only required if the global heartbeat mode is enabled. In other words, the regions are only used if heartbeat_mode = global is in the cluster stanza. If not, this stanza is ignored.

Parameters

Description

region

Heartbeat region UUID

cluster

Cluster name (should match the name in the cluster stanza)

While manual editing is not recommended, users doing so must follow the format strictly. The stanza should start at the first column and end with a colon. The parameters must start after a tab. A blank line must demarcate each stanza. Care should be taken to avoid stray white-spaces.

## EXAMPLE
The example below illustrates populating a cluster.conf with a cluster called webcluster, having 3 nodes and 3 global heartbeat regions, using the o2cb(8) utility.

```
$ o2cb add-cluster webcluster
$ o2cb add-node webcluster node7 --ip 192.168.0.107 --number 7
$ o2cb add-node webcluster node6 --ip 192.168.0.106 --number 6
$ o2cb add-node webcluster node10 --ip 192.168.0.110 --number 10
$ o2cb add-heartbeat webcluster /dev/sdg1
$ o2cb add-heartbeat webcluster /dev/sdk1
$ o2cb add-heartbeat webcluster /dev/sdh1
$ o2cb heartbeat-mode webcluster global
$ o2cb list-cluster webcluster
heartbeat:

        region = 77D95EF51C0149D2823674FCC162CF8B

        cluster = webcluster
heartbeat:

        region = DCDA2845177F4D59A0F2DCD8DE507CC3

        cluster = webcluster
heartbeat:

        region = BBA1DBD0F73F449384CE75197D9B7098

        cluster = webcluster
node:

        ip_port = 7777

        ip_address = 192.168.0.107

        number = 7

        name = node7

        cluster = webcluster
node:

        ip_port = 7777

        ip_address = 192.168.0.106

        number = 6

        name = node6

        cluster = webcluster
node:

        ip_port = 7777

        ip_address = 192.168.0.110

        number = 10

        name = node10

        cluster = webcluster
cluster:

        node_count = 3

        heartbeat_mode = global

        name = webcluster
```

## SEE ALSO
o2cb(7) o2cb(8) o2cb.sysconfig(5)

## AUTHORS
Oracle Corporation

## COPYRIGHT
Copyright © 2004, 2012 Oracle. All rights reserved.


oddjob.conf

package: oddjob

title: oddjob.conf(5)

text:
# oddjob.conf(5)

## NAME
oddjob.conf - configuration for oddjob for the system message bus

## DESCRIPTION
The /etc/dbus-1/system.d/oddjob.conf configuration file specifies D-Bus-level access controls for the com.redhat.oddjob service, in particular which users can invoke methods provided by the service. For more information, please see the D-Bus documentation.

## SEE ALSO
oddjob_request(1) oddjobd.conf(5) oddjobd(8)


oddjobd-introspection.conf

title: oddjobd-introspection.conf(5)

text:
# oddjobd-introspection.conf(5)

## NAME
oddjobd-introspection.conf - allow introspection of oddjobd

## DESCRIPTION
The /etc/oddjobd.conf.d/oddjobd-introspection.conf is typically processed along with other files in the /etc/oddjobd.conf.d directory.

## SEE ALSO
oddjob.conf(5)


oddjobd.conf

title: oddjobd.conf(5)

text:
# oddjobd.conf(5)

## NAME
oddjobd.conf - configuration for oddjobd

## DESCRIPTION
The /etc/oddjobd.conf configuration file specifies which services the oddjobd server provides over the D-Bus, and authorization rules which are enforced in addition to those enforced by the system message bus.

The configuration file is an XML document. The top-level element type is <oddjobconfig>, which contains one or more <service> elements. Each <service> describes a service which will be provided on the system-wide message bus.

Each <object> describes an object path which will will be recognized by the specified service. The object path may include wildcards, in which case any call to an object with a path name which matches the specified path will be accepted. An object contains one or more <interface> elements, each of which describes a group of methods described in <method> elements.

Each <method> element must specify the method name as a value for its name attribute and may include a <helper> element which the name of an executable to run as its exec attribute and the number of arguments which will be expected from the D-Bus client and passed to the helper as its argument_count attribute. The <helper>'s exec attribute can include one or more command line arguments, separated from the executable by whitespace. A <helper> may also include attributes indicating whether or not the invoking user's name should be prepended to the list of arguments received as part of the D-Bus request (prepend_user_name, with recognized values "yes" or "no"), and whether that set of arguments should be passed in to the helper via stdin (the default) or on its command line (argument_passing_method, with recognized values "stdin" and "cmdline").

Each <oddjobconfig>, <service>, <object>, <interface>, or <method> element may also include authorization elements <allow> and <deny>. Each <allow> or <deny> rule specifies some combination of a user name and/or a UID range which the invoking user must match for the rule to apply. A rule can also specify the caller's SELinux context, user, role, or execution domain, and be applied or not based on whether or not policy is being enforced. All <deny> rules for the method are checked first, followed by all of its <allow> rules. If no matches are found, the <deny> rules for the containing <interface> element are checked, followed by its <allow> rules, and so on. If all ACLs are searched and no matches turn up, access is denied.

The oddjobd server will automatically supply information used by the D-Bus introspection mechanism on behalf of your objects, but only if the client which is requesting the information is allowed to invoke the Introspect method of the org.freedesktop.DBus.Introspectable interface provided by the object.

The configuration file may also indicate that the contents of other files should be read by the configuration parser, using an <include> element.

## EXAMPLES
Here is an example file:

<?xml version="1.0"?>

<oddjobconfig/>

Another:

<?xml version="1.0"?>

<oddjobconfig>

<allow user="wally"/>

<service name="com.redhat.oddjob">

<allow user="polly"/>

<object name="/com/redhat/oddjob">

<allow user="holly"/>

<interface name="com.redhat.oddjob">

<allow user="bob"/>

<method name="pwd">

<helper exec="/bin/pwd" argument_count="0" prepend_user_name="no"/>

<allow user="jimmy"/>

<allow user="billy"/>

<allow min_uid="0" max_uid="1000"/>

</method>

<method name="reboot">

<helper exec="/sbin/reboot" argument_count="0"/>

</method>

<method name="flush-nscd">

<helper exec="/sbin/nscd -i passwd -i group -i hosts" argument_count="0"/>

</method>

</interface>

<interface name="org.freedesktop.DBus.Introspectable">

<allow min_uid="0" max_uid="0"/>

</interface>

</object>

</service>

<include ignore_missing="yes">/etc/oddjobd-local.conf</include>

<include ignore_missing="yes">/etc/oddjobd.conf.d/*.conf</include>

</oddjobconfig>

And another:

<?xml version="1.0"?>

<oddjobconfig>

<service name="com.example.management">

<object name="/com/example/power">

<interface name="com.example.shutdown">

<method name="reboot">

<allow user="root"/>

<helper exec="/sbin/reboot" argument_count="0"/>

</method>

</interface>

<interface name="org.freedesktop.DBus.Introspectable">

<allow min_uid="0" max_uid="0"/>

</interface>

</object>

<object name="/com/example/power">

<interface name="com.example.shutdown">

<method name="poweroff">

<allow user="root"/>

<helper exec="/sbin/poweroff" argument_count="0"/>

</method>

</interface>

<interface name="org.freedesktop.DBus.Introspectable">

<allow min_uid="0" max_uid="0"/>

</interface>

</object>

</service>

</oddjobconfig>

## SEE ALSO
oddjob_request(1) oddjob.conf(5) oddjobd(8)


oddjob-gpupdate.conf

package: oddjob-gpupdate

title: oddjob-gpupdate.conf(5)

text:
# oddjob-gpupdate.conf(5)

## NAME
oddjob-gpupdate.conf - system message bus configuration for oddjob-gpupdate

## DESCRIPTION
The /etc/dbus-1/system.d/oddjob-gpupdate.conf configuration file specifies D-Bus-level access controls for the ru.basealt.oddjob_gpupdate service, in particular which users can invoke methods provided by the service. For more information, please see the D-Bus documentation.

## SEE ALSO
dbus-daemon(1) oddjobd(8)


oddjobd-gpupdate.conf

title: oddjobd-gpupdate.conf(5)

text:
# oddjobd-gpupdate.conf(5)

## NAME
oddjobd-gpupdate.conf - allow limited use of the gpupdate functions

## DESCRIPTION
The /etc/oddjobd.conf.d/oddjobd-gpupdate.conf is typically processed along with other files in the /etc/oddjobd.conf.d directory.

The gpupdate helper itself accepts these options:

-q

Refrain from outputting the usual "Apply group policies for..." message when it applies group policies.

-p

Override the group policy applier binary (by default: /usr/sbin/gpoa).

## SEE ALSO
oddjob.conf(5)


oddjob-mkhomedir.conf

package: oddjob-mkhomedir

title: oddjob-mkhomedir.conf(5)

text:
# oddjob-mkhomedir.conf(5)

## NAME
oddjob-mkhomedir.conf - system message bus configuration for oddjob-mkhomedir

## DESCRIPTION
The /etc/dbus-1/system.d/oddjob-mkhomedir.conf configuration file specifies D-Bus-level access controls for the com.redhat.oddjob_mkhomedir service, in particular which users can invoke methods provided by the service. For more information, please see the D-Bus documentation.

## SEE ALSO
dbus-daemon(1) oddjobd(8)


oddjobd-mkhomedir.conf

title: oddjobd-mkhomedir.conf(5)

text:
# oddjobd-mkhomedir.conf(5)

## NAME
oddjobd-mkhomedir.conf - allow limited use of the mkhomedir functions

## DESCRIPTION
The /etc/oddjobd.conf.d/oddjobd-mkhomedir.conf is typically processed along with other files in the /etc/oddjobd.conf.d directory.

The mkhomedir helper itself accepts these options:

-q

Refrain from outputting the usual "Creating home directory..." message when it creates a home directory.

-n

Only create the home directory; do not populate it using the contents of the skeleton directory.

-s

Override the location of the skeleton directory (by default: /etc/skel).

-u

Specify a umask whose bits are masked off of contents of the skeleton directory while they are copied to the user's new home directory. The default is read from /etc/login.defs by taking HOME_MODE and UMASK values, in this order. First found value persists.

## SEE ALSO
oddjob.conf(5) login.defs(5)