---
name: "gfservice"
section: "1"
platform: "linux"
package: "gfarm-client"
version: "2.7.20+dfsg-1.2+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/gfservice"
---

# gfservice(1)

control Gfarm servers from a remote host

## NAME

gfservice - control Gfarm servers from a remote host

## SYNOPSIS

**gfservice** \[*options*\] sub-command \[host-id\] \[*argument ...*\]

## DESCRIPTION

**gfservice** is an utility for Gfarm administrators to operate servers (**gfmd**, **gfsd** and PostgreSQL) on remote hosts. OpenLDAP is not supported currently. It can start, stop, set up (execute **config-gfarm** and **config-gfsd**) and clean up the servers, for example.

A sample command line of **gfservice** looks like:

```
	gfservice start-gfmd gfmd2
```

where "*start-gfmd*" is a sub-command and *gfmd2* is a host-id respectively. Executing the command, **gfservice** tries to start gfmd on the host named *gfmd2*. To specify a remote server host, **gfservice** uses host-id instead of hostname. All host-ids (*gfmd1*, *gfmd2*, and so on) are defined in a configuration file of **gfservice**. Here is an example of the configuration file:

```
	gfmd1=metadb1.example.com
	gfmd1_CONFIG_GFARM_OPTIONS="-A $LOGNAME -X"
	gfmd2=metadb2.example.com
	gfmd2_CONFIG_GFARM_OPTIONS="-A $LOGNAME -X"
	gfsd1=spool1.example.com
	gfsd2=spool2.example.com
```

**gfservice** determines a path of the configuration file to be read with the following procedures:

 1\. **-f** *file* option is specified, read *file*.

 2\. Otherwise, the environment variable *GFSERVICE\_CONF* is defined and not empty, read the file.

 3\. Otherwise, read $HOME/.gfservice.

If **gfservice** fails to read a configuration file, it prints an error message and exits immediately. Note that the configuration file itself is a Bourne-shell script and **gfservice** includes (exactly to say, *evaluates*) the file. See gfservice.conf(5) for more details about the configuration file.

**gfservice** uses SSH (Secure Shell) to connect with a remote host. Since it may execute **ssh** several times during a sub-command operation, it is recommended to use an SSH agent (e.g. **ssh-agent** of OpenSSH) or an authentication key with an empty passphrase to avoid typing a passphrase every time.

In addition with SSH, **gfservice** uses Sudo to get root privilege on the remote host. Please add a line like below to sudoers file (Sudo's configuration file) on each remote host.

```
	user ALL=(root, _gfarmfs, _gfarmmd) NOPASSWD: gfservice-agent
```

where *user* is an user name who executes **gfservice**. The NOPASSWD option is not mandatory, but **sudo** may ask you a password several times if omitted.

Since **gfservice** executes an agent command named **gfservice-agent** on the remote host using SSH and Sudo, **gfservice-agent** command must have been installed on all hosts you want to operate using **gfservice**.

**gfservice** has a plug-in system so that user can add new sub-commands. See "PLUG-IN SYSTEM" section of this man page for more details.

## OPTIONS

- **-d**

  Print debug information. **gfservice** passes this option to **gfservice-agent** so that also **gfservice-agent** outputs debug information.

- **-f** *file*

  Read configuration from *file* instead of the default.

- **-t** *time*

  Set operation timeout in *time* seconds. When **gfservice** tries to start or stop a server program (gfmd, gfsd or a backend database), it waits until the operation is complete or *time* interval is elapsed. If "no" is specified as *time*, timeout never occurs. The default value is "no".

- **-k**

  When this option is specified with sub-command **config-gfarm** or **config-gfarm-master**, **gfservice** creates a shared secret key files using **gfkey** command.

## SUB-COMMANDS FOR GFMD

The followings are sub-commands which operate **gfmd**. The given host-id argument must be "gfmd*n*" (gfmd1, gfmd2, ...). Otherwise **gfservice** reports an error and exits immediately.

**backend-db-status** *host-id*

Exit with an exit code 0, if a backend database is currently running. Otherwise exits with 1.

**gfmd-status** *host-id*

Exit with an exit code 0, if **gfmd** is currently running. Otherwise exits with 1.

**start-backend-db** *host-id*

Start a backend database if it is not running currently.

**start-gfmd** *host-id*

Start **gfmd** if it is not running currently.

**start-gfmd-master** *host-id*

An alias of "**start-gfmd**" sub-command.

**start-gfmd-slave** *host-id*

This sub-command is the same as "**start-gfmd**", but **-S** option is added to **gfmd**.

**start-gfarm** *host-id*

Start a backend database and **gfmd** if they are not running currently.

**start-gfarm-master** *host-id*

An alias of "**start-gfarm**" sub-command.

**start-gfarm-slave** *host-id*

This sub-command is the same as "**start-gfarm**", but **-S** option is added to **gfmd**.

**stop-backend-db** *host-id*

Stop a backend database if it is running currently.

**stop-gfmd** *host-id*

Stop **gfmd** if it is running currently.

**stop-gfarm** *host-id*

Stop **gfmd** and a backend database if they are running currently.

**kill-gfmd** *host-id*

Kill **gfmd** (send SIGKILL) if it is running currently.

**restart-backend-db** *host-id*

Perform "**stop-backend-db**" and "**start-backend-db**" sub-commands successively.

**restart-gfmd** *host-id*

Perform "**stop-gfmd**" and "**start-gfmd**" sub-commands successively.

**restart-gfmd-master** *host-id*

An alias of "**restart-gfmd**" sub-command.

**restart-gfmd-slave** *host-id*

Perform "**stop-gfmd**" and "**start-gfmd-slave**" sub-commands successively.

**restart-gfarm** *host-id*

Perform "**stop-gfarm**" and "**start-gfarm**" sub-commands successively.

**restart-gfarm-master** *host-id*

An alias of "**restart-gfarm**" sub-command.

**restart-gfarm-slave** *host-id*

Perform "**stop-gfarm**" and "**start-gfarm-slave**" sub-commands successively.

**promote** *host-id*

Promote **gfmd** from a slave to a master.

**promote-gfmd** *host-id*

An alias of "**promote**" sub-command.

**set-gfmd-conf** *host-id* *directive* *value*

Add

```
	directive value
```

line to gfmd.conf file on the remote host. If gfmd.conf already has a *directive* line, **gfservice** deletes it and then add a new line.

**set-gfsd-conf** *host-id* *directive* *value*

Add

```
	directive value
```

line to gfsd.conf file on the remote host. If gfsd.conf already has a *directive* line, **gfservice** deletes it and then add a new line.

**unset-gfmd-conf** *host-id* *directive*

Delete a *directive* line in gfmd.conf file on the remote host. If gfmd.conf file doesn't contain *directive* line, the file is unchanged.

**unset-gfsd-conf** *host-id* *directive*

Delete a *directive* line in gfsd.conf file on the remote host. If gfsd.conf file doesn't contain *directive* line, the file is unchanged.

**backup-backend-db**

Backup a backend database on the remote host and output the backup data to standard out.

**backup-gfmd-conf** *host-id*

Output gfmd.conf file on the remote host to standard out.

**backup-gfsd-conf** *host-id*

Output gfsd.conf file on the remote host to standard out. This sub-command can be worked only when the remote host is configured in the private mode.

**backup-usermap** *host-id*

Output usermap file on the remote host to standard out. This sub-command can be worked only when the remote host is configured in the private mode.

**restore-backend-db** *host-id*

Restore a backend database on the remote host. The backup data are read from standard in.

**restore-gfmd-conf** *host-id*

Recover gfmd.conf file on the remote host. **gfservice** reads a backup of gfmd.conf from standard in.

**restore-gfsd-conf** *host-id*

Recover gfsd.conf file on the remote host. **gfservice** reads a backup of gfsd.conf from standard in. This sub-command can be worked only when the remote host is configured in the private mode.

**restore-usermap** *host-id*

Recover usermap file on the remote host. **gfservice** reads a backup of usermap from standard in. This sub-command can be worked only when the remote host is configured in the private mode.

**config-gfarm** *host-id*

Execute **config-gfarm** command on the remote host. If "gfmd*n*\_CONFIG\_GFARM\_OPTIONS" variable is declared in the configuration file of **gfservice**, its value is passed to **config-gfarm** command as options. Don't use this sub-command when you want to enable replication of gfmd. Instead, use "**config-gfarm-master**" or "**config-gfarm-slave**" sub-command in that case. If **-k** option is specified, **gfservice** also creates a shared secret key files onto the gfmd host, using **gfkey** command.

**config-gfarm-master** *host-id*

This sub-command is the same as **config-gfarm** but gfmd replication is enabled automatically.

**config-gfarm-slave** *host-id* *master-host-id*

This sub-command is the same as **config-gfarm** but gfmd replication is enabled automatically and the remote gfmd host is configured as a slave of *master-host-id*. Then **gfservice** registers the slave host to a server list using **gfmdhost** command. **gfservice** also adds the slave host to *metadb\_server\_list* directive in gfarm2.conf file on the master gfmd host and distribute the updated gfarm2.conf file to all hosts defined in the configuration file. It also updates gfsd.conf file and distributes it to all gfmd and gfsd hosts, if "gfmd*n*\_PRIVATE\_MODE" variable is set to "true". If the value of the variable "gfmd*n*\_AUTH\_TYPE" is "sharedsecret", it also copies a shared key file from the maste gfmd to the slave gfmd host.

**unconfig-gfarm** *host-id*

Execute "**stop-gfarm**" sub-command and then delete all files and directories created by gfmd and a backend database. If you want to unconfigure a slave gfmd, use "**unconfig-gfarm-slave**" sub-command instead.

**unconfig-gfarm-master** *host-id*

An alias of "**unconfig-gfarm**" sub-command.

**unconfig-gfarm-slave** *host-id* *master-host-id*

This sub-command is the same as "**unconfig-gfarm**", but **gfservice** does some additional works. It also deletes the slave host from a server list using **gfmdhost** command and from *metadb\_server\_list* directive in gfarm2.conf file on all hosts defined in the configuration file. It also updates gfsd.conf file and distributes it to all gfmd and gfsd hosts, if "gfmd*n*\_PRIVATE\_MODE" variable is set to "true".

## SUB-COMMANDS FOR GFSD

The followings are sub-commands which operate **gfsd**. The given host-id argument must be "gfsd*n*" (gfsd1, gfsd2, ...). Otherwise **gfservice** reports an error and exits immediately.

**gfsd-status** *host-id*

Exit with an exit code 0, if **gfsd** is currently running. Otherwise exits with 1.

**start-gfsd**

Start **gfsd** if it is not running currently.

**stop-gfsd**

Stop **gfsd** if it is running currently.

**restart-gfsd** *host-id*

Perform "**stop-gfsd**" and "**start-gfsd**" sub-commands successively.

**set-gfsd-conf** *host-id* *directive* *value*

Same as **set-gfsd-conf** sub-command for gfmd.

**unset-gfsd-conf** *host-id* *directive*

Same as **unset-gfsd-conf** sub-command for gfmd.

**backup-gfsd-conf** *host-id*

Same as **backup-gfsd-conf** sub-command for gfmd.

**backup-usermap** *host-id*

Same as **backup-usermap** sub-command for gfmd.

**restore-gfsd-conf** *host-id*

Same as **restore-gfsd-conf** sub-command for gfmd.

**restore-usermap** *host-id*

Same as **restore-usermap** sub-command for gfmd.

**config-gfsd** *host-id*

Execute "**config-gfsd**" command on the remote host. If "gfsd*n*\_CONFIG\_GFSD\_OPTIONS" variable is declared in the configuration file of **gfservice**, its value is passed to **config-gfsd** command as options. **gfservice** also registers the configured remote host as a filesystem node using **gfhost** command. If the value of the variable "gfsd*n*\_AUTH\_TYPE" is "sharedsecret", it also copies a shared key file from gfmd1 to the gfsd host.

**unconfig-gfsd** *host-id*

Execute "**stop-gfsd**" sub-command and then delete all files and directories created by gfsd.

## SUB-COMMANDS FOR CLIENT

The followings are sub-commands which operate a client. The given host-id argument must be "gfmd*n*" (gfmd1, gfmd2, ...), "gfsd*n*" (gfsd1, gfsd2, ...) or "client*n*" (client1, client2, ...). Otherwise **gfservice** reports an error and exits immediately.

**mount** *host-id* *directory* *option...*

Mount a Gfarm2 filesystem on *directory* on the remote host. The argument *option* is an option to **gfarm2fs** command.

**unmount** *host-id* *directory*

Unmount a Gfarm2 filesystem on *directory* on the remote host.

**umount** *host-id* *directory*

An alias of "**unmount**" sub-command.

**set-gfarm-conf** *host-id* *directive* *value*

Add

```
	directive value
```

line to gfarm2.conf file on the remote host. If gfarm2.conf already has a *directive* line, **gfservice** deletes it and then add a new line.

**unset-gfarm-conf** *host-id* *directive*

Delete a *directive* line in gfarm2.conf file on the remote host. If gfarm2.conf file doesn't contain *directive* line, the file is unchanged.

**backup-gfarm-conf** *host-id*

Output gfarm2.conf file on the remote host to standard out.

**backup-shared-key** *host-id*

Output a shared secret key file to standard out.

**restore-gfarm-conf** *host-id*

Recover gfarm2.conf file on the remote host. **gfservice** reads a backup of gfarm2.conf from standard in.

**restore-shared-key** *host-id*

Recover a shared secret key file on the remote host. **gfservice** reads a backup of the shared secret key from standard in.

**config-client** *host-id*

Copy gfarm2.conf file from gfmd1 to the client host. If the value of the variable "client*n*\_AUTH\_TYPE" is "sharedsecret", it also copies a shared key file from gfmd1 to the client host.

**unconfig-client** *host-id*

Delete gfarm2.conf file and a shared secret key file on the remote host.

**gfcmd** *host-id* *command-name* *command-argument ...*

Execute a Gfarm command on the remote host.

**gfcmd-root** *host-id* *command-name* *command-argument ...*

Execute a Gfarm command on the remote host with root privilege.

**grid-proxy-init** *host-id* *command-argument ...*

Execute **grid-proxy-init** command on the remote host.

## SUB-COMMANDS FOR MULTIPLE HOSTS

The followings are sub-commands which operate on multiple hosts. The host-id argument must not be specified.

**start-all**

Start all backend databases, **gfmd** servers and **gfsd** servers.

**stop-all**

Stop all **gfsd** servers, **gfmd** servers and backend databases,

**kill-gfmd-all**

Kill (send SIGKILL) all **gfmd** servers.

**restart-all**

Perform "**stop-all**" and "**start-all**" sub-commands successively.

**config-all**

Perform "**config-gfarm-master**" for *gfmd1* and "**config-gfarm-slave**" for all other gfmd nodes. Then, perform "**config-gfsd**" for all gfds nodes. Finally, perform "**config-client**" for all client nodes.

**unconfig-all**

Perform "**unconfig-client**" for all client nodes. Then, perform "**unconfig-gfsd**" for all gfds nodes. Finally, perform "**unconfig-gfarm**" for all gfmd nodes.

## PLUG-IN SYSTEM

**gfservice** has a plug-in system so that user can add new sub-commands. If given sub-command is not provided by **gfservice**, **gfservice** refers to a file which has name of sub-command under %%DATADIR%%/gfarm/gfservice directory.

Sub-command file must be written as Bourne shell script. Sub-command file for sub-command "*name*", must have shell function named "**subcmd\_***name*" which will be executed from **gfservice**, and "**subcmd\_***name***\_agent**" which will be executed from **gfservice-agent**.

For the case a sub-command depends on a other user provided sub-command, Sub-command file for sub-command "*name*", must have shell function named "*name***\_depends**" which must return list of sub-commands. List of sub-commands must be a string which is space separated list of sub-command names. If sub-command or it's agent does not have dependencies, return empty string. Similarly, sub-command file must have shell function named "*name***\_agent\_depends**" which must return list of sub-command's agents.