20 Jan 2015
config-gfarm 8 Gfarm
config-gfarm set up a metadata server of Gfarm
`config-gfarm` options

## DESCRIPTION

`config-gfarm` is a utility to set up a metadata server of Gfarm file system. The server program for a metadata server is named `gfmd`. `config-gfarm` is required to be run with the root privilege, unless you use the file system for private purpose such as development, evaluation or test of Gfarm.

`config-gfarm` performs the following processes, in that order:

1. Set up the backend database.

2. Generate Gfarm configuration files `%%SYSCONFDIR%%/gfarm2.conf` and `%%SYSCONFDIR%%/gfmd.conf`.

3. Create scripts (or configuration files) to start/stop the backend database and `gfmd`.

   On most systems, `config-gfarm` puts start/stop scripts `gfmd` and `gfarm-pgsql` onto either `/etc/init.d` or `/etc/rc.d/init.d`, according to the operating system.

   On Linux with systemd such as Red Hat Enterprise Linux 7 or later, `config-gfarm` puts the unit configuration files `gfmd.service` and `gfarm-pgsql.service` onto `/etc/systemd/system`, and then executes `systemctl enable gfmd.service` and `systemctl enable gfarm-pgsql.service` respectively.

4. Start the backend database and `gfmd`.

5. Put the script `unconfig-gfarm.sh` on %%SYSCONFDIR%%. The script does unconfiguration of the metadata server. It stops `gfmd` and the backend database, and removes all files created by `config-gfarm` including `unconfig-gfarm.sh` itself.

Before set up a metadata server using `config-gfarm`, it is recommended to execute `config-gfarm -t`. With `-t` option, the sets up is not performed. Instead, it shows values of all configurable parameters:

    $ config-gfarm -t
    prefix                 [--prefix]:
    metadata backend             [-b]: postgresql
    (available backend: postgresql )
    metadata     directory       [-l]: /var/gfarm-pgsql
    metadata log directory       [-L]: /var/gfarm-pgsql/pg_xlog
    postgresql admin user        [-U]: miles
    postgresql admin password    [-W]: (auto generated)
    postgresql user              [-u]: gfarm
    postgresql password          [-w]: (auto generated)
    postgresql prefix            [-P]: /usr
    postgresql version           [-V]: 9.2
    postgresql XML supported     [-X]: no
    metadata replication         [-r]: no
    metaserver hostname          [-h]: host1.example.org
    matadata admin user          [-A]: miles
    matadata admin dn            [-D]:
    portmaster port              [-p]: 10602
    gfmd port                    [-m]: 601
    auth type                    [-a]: sharedsecret
    rc script for gfmd               : /etc/init.d/gfmd
    rc script for backend            : /etc/init.d/gfarm-pgsql
    gfmd conf file                   : /etc/gfmd.conf
    gfarm client conf file           : /etc/gfarm2.conf
    gfmd pid file                    : /var/run/gfmd.pid
    backend pid file                 : /var/run/postmaster.pid

The option name surrounded by [ ] means that you can specify a value with that option.

## OPTIONS

`--prefix` path

  Configure some paths related to `gfmd` and the backend database. Specifically, the followings are affected.

  - The directory to put metadata of Gfarm. That is `PREFIX/var/gfarm-pgsql` if the backend database is PostgreSQL. The path can also be changed by `-l` option. When both options are specified, `-l` option has preference.

  - The directory to put log files about metadata. That is `PREFIX/var/gfarm-pgsql/pg_xlog` if the backend database is PostgreSQL. The path can also be changed by `-L` option. When both options are specified, `-L` option has preference.

  - The directory to put journal files of `gfmd`. That is `PREFIX/var/gfarm-metadata/journal`. The path can also be changed by `-j` option. When both options are specified, `-j` option has preference.

  - The directory to put PID files of `gfmd` and the backend database. That is `PREFIX/var/run`.

  - The directory to put configuration files. That is `PREFIX/etc`.

  - The directory of start/stop scripts for `gfmd` and its backend database. That is `PREFIX/etc/init.d` or `PREFIX/rc.d/init.d/etc` which is depending on operating systems.

  - If systemd is running on the host, there is a special exception. When an empty prefix is given by `--prefix` option on such host, `config-gfarm` doesn't put unit configuration files for systemd. Instead, it puts traditional start/stop scripts at `PREFIX/etc/init.d`.

  - The unconfiguration script `unconfig-gfarm.sh`. That is `PREFIX/etc/unconfig-gfarm.sh`.

  The default is "" (empty).

`-b` backend

  Specify backend database. It currently supports "postgresql" (for PostgreSQL) only. "ldap" (for LDAP) was supported in the past, but not maintained any longer. `config-gfarm -t` lists which backend databases are available.

  PostgreSQL is chosen by default if "postgresql" is in the list. If the available backend is "ldap" only, it is still chosen by default. Note that you need to recompile Gfarm if you'd like to make Gfarm on your system support a backend database not in the list.

`-d` digest_type

  Enable checksum calculation and specify the digest type of the checksum. The digest_type argument is a lower-case name which is supported by the OpenSSL library on the host, such as "md5".

`-U` username

  Specify administrator's username of the Gfarm file system. Since the default value differs depending on operating systems, execute `config-gfarm -t` to confirm the username.

`-u` username

  The configured `gfmd` will connect to the backend database as the specified username. The default is "gfarm".

`-P` prefix

  Specify an installation prefix of the backend database (e.g. /usr/local). When `config-gfarm` executes an administration command of the backend database, it assumes the command is installed under the given prefix. An example of those commands is `initdb` of PostgreSQL. If this option is omitted, `config-gfarm` searches directories listed in the environment variable `PATH` for the commands.

`-V` version

  Tell version of the backend database to `config-gfarm`. In most cases, `config-gfarm` can detect a correct version number by itself. This option should be used only when `config-gfarm` fails to get the correct version number.

`-l` directory

  Specify a path to the directory where the backend database puts files to store metadata of Gfarm.

  If the backend database is PostgreSQL, the directory is commonly called PGDATA directory. The default is `PREFIX/var/gfarm-pgsql` where PREFIX is a prefix given by `--prefix` option.

`-L` directory

  Specify a path to the directory where the backend database puts log files. If the backend database is PostgreSQL, the default is `PREFIX/var/gfarm-pgsql/pg_xlog` where PREFIX is a prefix given by `--prefix` option.

`-h` hostname

  Specify a hostname which is used to identify the metadata server. The default is the fully qualified domainname of the host.

`-j` directory

  Specify a path to the directory where `gfmd` puts journal files. This option takes an effect only when metadata replication is enabled by `-r` option. The default value is `PREFIX/var/gfarm-metadata/journal` where PREFIX is a prefix given by `--prefix` option.

`-A` username

  Specify administrator of the Gfarm file system. If this option is omitted, `config-gfarm` gets a username by executing `who am i` command.

`-D` subject-dn

  Specify a subject DN of global administrator. This option is mandatory, in case that the authentication method is GSI,

`-p` port

  Specify a TCP port number the configured backend database listens on. The default is 10602.

`-m` port

  Specify a TCP port number the configured `gfmd` listens on. The default value is 10601 in case of the private mode, 601 otherwise.

`-a` method

  Specify an authentication method. It currently recognizes "sharedsecret" or "gsi". The default is "sharedsecret".

`--help`

  Show usage, then exit.

`-S`

  Enable the private mode. `config-gfarm` sets up the Gfarm file system which can be run without root privilege. Specifically, `config-gfarm` changes the configuration procedures as follows:

  - The default listen port of `gfmd` (corresponding with `-m` option) is changed from 601 to 10601.

  - The user map file `%%SYSCONFDIR%%/usermap` is also created. The metadata server reads this file when it starts. In the non-private mode, it is required to create the user accounts for _gfarmmd and _gfarmfs on the operating system. With the user map file, the creation of the user accounts is not needed. The file defines mappings of Gfarm system users to actual user accounts.

  - The configuration file for gfsd, `%%SYSCONFDIR%%/gfsd.conf` is also created. In the non-private mode, gfsd reads the configuration file `%%SYSCONFDIR%%/gfarm2.conf` instead, which is read by all Gfarm programs connecting with a metadata server. `%%SYSCONFDIR%%/gfsd.conf` is a configuration file cutomized for gfsd running under the private mode.

  `-S` option never changes locations of start/stop scripts and configuration files. Since the default locations of those files are usually writable only for privilege users, `config-gfarm` fails to create them. To avoid this problem, also specify `--prefix` option.

`-N`

  Do not start `gfmd` or the backend database.

`-f`

  Force overwriting an existing set up.

`-t`

  Show values of all configurable parameters in human readable format, then exit immediately.

`-T`

  Like `-t` option, but it shows values in KEY=VALUE format.

`-r`

  Enable metadata replication among metadata servers.

`-W` password

  Specify administrator's password of backend database. This option corresponds with `-U` option which specifies the username. By default, the password is generated automatically.

`-w` password

  The configured `gfmd` will connect the backend database with the specified password. This option corresponds with `-u` option which specifies the username. By default, the password is generated automatically.

`-X`

  Enable XML Path Language (XPath) support for querying XML extended attributes.

`-E`

  Set up PostgreSQL with the data checksums option. `config-gfarm` gives `--data-checksums` option to `initdb` command of PostgreSQL. Note that PostgreSQL 9.3 or later is required to use this feature. This option takes an effect only when the backend database is PostgreSQL.

## FILES

`%%SYSCONFDIR%%/gfarm2.conf`

  configuration file for Gfarm clients

`%%SYSCONFDIR%%/gfmd.conf`

  configuration file for `gfmd`

`%%SYSCONFDIR%%/gfsd.conf`

  configuration file for gfsd (used only in the private mode)

`%%SYSCONFDIR%%/usermap`

  user mapping definition file (used only in the private mode)

`/etc/init.d/gfarm-pgsql`

  start/stop script for PostgreSQL running as backend database of Gfarm

`/etc/init.d/gfmd`

  start/stop script for `gfmd`

`/etc/systemd/system/gfarm-pgsql.service`

  unit configuration file for PostgreSQL running as backend database of Gfarm, read by systemd

`/etc/systemd/system/gfmd.service`

  unit configuration file for `gfmd`, read by systemd

## SEE ALSO

gfarm2.conf 5, config-gfsd 8