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 parentheses, 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 occurring 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)

summary: [Configuration of findlib/ocamlfind]

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 OCaml 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 OCaml 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 OCaml 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 OCaml 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)

summary: [Location of package directories]

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)


package: open-isns

title: isns_config(5)

text:
# isns_config(5)

## NAME
isns_config - iSNS configuration file

## SYNOPSIS
/etc/isns/isnsadm.conf

/etc/isns/isnsd.conf

/etc/isns/isnsdd.conf

## DESCRIPTION
All Open-iSNS utilities read their configuration from a file in /etc/isns. There is a separate configuration file for each application, isnsd, isnsadm, and isnsdd. The syntax and the set of supported options is identical, even though some options are specific to e.g. the server. Unless indicated, options are applicable to all utilities.

An Open-iSNS configuration file contains keyword-argument pairs, one per line. All keywords are case insensitive.

A # character introduces a comment, which extends until the end of the line. Empty lines are ignored.

There are no line continuations, and you cannot use quotes around arguments.

Some options specify timeout values, which are given in units of seconds by default. You can specify an explicit unit, however, such as d (days), h (hours), m (minutes), or s (seconds).

### Generic Options
HostName

By default, Open-iSNS applications will retrieve the machine's hostname using the gethostname(3) system call, and use a DNS lookup to look up the canonical name. Using the HostName option, you can override this. This option is rarely needed.

SourceName

This option is mandatory for all Open-iSNS applications. This should be a name which identifies the client uniquely. There are two readings of RFC 4171; one requires that this is an iSCSI qualified name such as iqn.2001-04.com.example.host, whereas other language in the RFC suggests that this is pretty much a free-format string that just has to be unique (using e.g. the client's fully qualified domain name).

When using DSA authentication, Open-iSNS currently requires the source name to match the key identifier (SPI) of the client's public key.

If left empty, the source name is derived from either from the default initiatorname in /etc/iscsi/initiatorname.iscsi or, failing that, the client's hostname using the IQNPrefix option to generate an iSCSI qualified name.

IQNPrefix

Specifies the iSCSI qualified name prefix; must be of the form iqn.YYYY-MM with YYYY being the year and MM the month.

ServerAddress (client):

This options specifies the host name or address of the iSNS server to talk to. It can optionally be followed by a colon, and a port number.

Instead of a hostname, IPv4 or IPv6 addresses can be used. In order to avoid ambiguities, literal IPv6 addresses must be surrounded by square brackets, as in [2001:4e5f::1].

When specifying a port number, you can use either the numeric port, or a string name to be looked up in /etc/services. When the port is omitted, it defaults to 3205, the IANA assigned port number of iSNS.

If the special string SLP: is used, the client will try to locate the iSNS server through SLP.

SLPRegister (server):

If set to 1, the iSNS daemon will register itself will the SLP service. This allows clients to contact the server without having to configure its address statically.

PIDFile (server):

This specifies the name of the server's PID file, which is /var/run/isnsd.pid by default.

### Database Related Options
These options apply to the iSNS server only, and control operation of the iSNS database.

Database

This option is used to specify how the database is stored. Setting this to an absolute path name will make isnsd keep its database in the specified directory.

If you leave this empty, isnsd will keep its database in memory. This is also the default setting.

DefaultDiscoveryDomain

iSNS scopes visibility of other nodes using so-called Discovery Domains. A storage node A will only "see" storage node B, if both are members of the same discovery domain.

So if a storage node is registered which is not part of any discovery domain, it will not see any other nodes.

By setting DefaultDiscoveryDomain=1, you can tell isnsd to create a virtual "default discovery domain", which holds all nodes that are not part of any administratively configured discovery domain.

By default, there is no default discovery domain.

RegistrationPeriod

The iSNS server can purge registered entities after a certain period of inactivity. This is called the registration period. Clients who register objects are supposed to refresh their registration within this period.

The default value is 1 hour. Setting it to 0 disables expiry of entities from the database.

ESIRetries

Open-iSNS is able to monitor the reachability of storage nodes and their portals by using a protocol feature called ESI (Entity status inquiry). Clients request ESI monitoring by registering an ESI port along with each portal. The server will send ESI messages to these portals at regular intervals. If the portal fails to reply several times in a row, it is considered dead, and will be removed from the database.

ESIRetries specifies the maximum number of attempts the server will make at contacting the portal before pronouncing it dead. If set to 0, the server will disable ESI and reject any registrations that specify an ESI port with an error code of "ESI not supported".

The default value is 3.

ESIMinInterval

This timeout value specifies the minimum ESI interval. If a client requests an ESI interval less than this value, it is silently rounded up.

The default value is 60 seconds.

ESIMaxInterval

This timeout value specifies the maximum ESI interval. If a client requests an ESI interval greater than this value, it is silently rounded down.

The default value is 10 minutes.

The maximum ESI interval must not exceed half the value of the registration period.

SCNRetries

iSNS clients can register to receive State Change Notification (SCN) messages to learn about changes in the iSNS database. This value specifies how often the server will try to retransmit an SCN message until giving up.

The default value is 3.

SCNCallout

This is the path name of a helper program that isnsdd will invoke whenever it processes a state change notification from the server. The helper program will be invoked with an argument indicating the type of event, being one of add, update, or remove. This is followed by a list of attributes in name=value notation, using the names and conventions described in isnsadm(8).

### Security Related Options
The iSNS standard defines an authentication method based on the DSA algorithm. Participants in a message exchange authenticate messages by adding an "authentication block" containing a time stamp, a string identifying the key used, and a digital signature of the message. The same method is also used by SLP, the Service Location Protocol.

The string contained in the authentication block is referred to as the Security Policy Index(SPI). This string can be used by the server to look up the client's public key by whatever mechanism; so the string could be used as the name of a public key file in a directory, or to retrieve an X509 certificate from LDAP.

From the perspective of Open-iSNS client applications, there are only two keys: the client's own (private) key, used to sign the messages it sends to the server, and the server's public key, used to verify the signatures of incoming server messages.

The iSNS server needs, in addition to its own private key, access to all public keys of clients that will communicate to it. The latter are kept in what is called a key store. Key stores and their operation will be discussed in section Key Stores and Policy below.

The following configuration options control authentication:

Security

This enables or disables DSA authentication. When set to 1, the client will sign all messages, and expect all server messages to be signed.

When enabling security in the server, incoming messages are checked for the presence of an auth block. If none is present, or if the server cannot find a public key corresponding to the SPI, the message is treated as originating from an anonymous source. If the SPI is known but the signature is incorrect, the message is dropped silently.

Messages from an anonymous source will be assigned a very restrictive policy that allows database queries only.

Setting this option to 0 will turn off authentication.

The default value is -1, which tells iSNS to use authentication if the required keys are installed, and use unauthenticated iSNS otherwise.

AuthName

This is the string that will be used as the SPI in all outgoing messages that have an auth block. It defaults to the host name (please refer to option HostName).

AuthKeyFile

This is the path name of a file containing a PEM encoded DSA key. This key is used to sign outgoing messages. The default is /etc/isns/auth_key.

ServerKeyFile

This option is used by client applications only, and specifies the path name of a file containing a PEM encoded DSA key. This key is used to authenticate the server's replies. The default is /etc/isns/server_key.pub.

KeyStore

This server-side option specifies the key store to use, described in the next section.

The following two options control how iSNS will verify the time stamp contained in the authentication block, which is supposed to prevent replay attacks.

Auth.ReplayWindow

In order to compensate for clock drift between two hosts exchanging iSNS messages, Open-iSNS will apply a little fuzz when comparing the time stamp contained in the message to the local system time. If the difference between time stamp and local system time is less than the number of seconds given by this option, the message is acceptable. Otherwise, it is rejected.

The default value is 5m.

Auth.TimestampJitter

When verifying incoming messages, Open-iSNS checks that the time stamps sent by the peer are increasing monotonically. In order to compensate for the reordering of messages by the network (eg when using UDP as transport), a certain time stamp jitter is accepted. If the time stamp of an incoming messages is no earlier than TimestampJitter seconds before the last time stamp received, then the message is acceptable. Otherwise, it is rejected.

The default value is 1s.

### Key Stores and Policy
The current implementation supports two types of key stores.

The simple key store uses a flat directory to store public keys, each key in a file of its own. The file is expected to hold the client's PEM-encoded public key, and it must use the client's SPI as the name. This type of key store is not really recommended, as it does not store any policy information.

A simple key store can be configured by setting the KeyStore option to the path name of the directory.

The recommended approach is to use the database as key store. This uses vendor-specific policy objects to tie SPI string, public key, entity name, source name and other bits of policy together, and store them in a persistent way.

The database key store is configured by setting the KeyStore option to the reserved value DB:, which is also the default.

Currently, Open-iSNS policy objects have the following attributes, besides the SPI:

Source:

This is the source node name the client must use. It defaults to the SPI string.

Functions:

This is a bitmap detailing which functions the client is permitted to invoke. The bit names correspond to the shorthand names used in RFC 4171, such as DevAttrReg, DevAttrQry, etc. The default is to allow registration, query and deregistration, as well as SCNRegister.

Entity name:

This is the entity name assigned to the client. If set, a registration by the client is not permitted to use a different entity name. If the client sends a registration without Entity identifier, the server will assign the entity name given in the policy. The default is to not restrict the entity name.

Object access:

This is a bitfield describing access permissions for each object type. For each object type, you can grant Read and/or Write permissions. Read access applies to the Query and GetNext calls; all other operations require write permission. The default grants read and write access to objects of type Entity, Storage Node, Portal and Portal Group; and read access to Discovery Domains.

Node types:

This bitfield describes which types of storage nodes a client is allowed to register; the valid bit names are target, initiator and control. The default is to restrict nodes to register initiators only.

### Network Related Options
Network.MaxSockets

This is the number of incoming connections accepted, and defaults to 1024. This usually applies to server side only, but is relevant if you create a passive TCP socket for ESI or SCN.

Network.ConnectTimeout

This is a timeout value, which specifies the time to wait for a TCP connection to be established. It defaults to 60s.

Network.ReconnectTimeout

When a connection attempt failed, we wait for a short time before we try connecting again. This is intended to take the pressure off overloaded servers. The default value is 10s.

Network.CallTimeout

Total amount of time to wait before timing out a call to the iSNS server. The default value is 60s.

## SEE ALSO
RFC 4171, isnsd(8), isnsadm(8).

## AUTHORS
Olaf Kirch <olaf.kirch@oracle.com>