'\" t
.\"     Title: gfhost
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 20 Jan 2010
.\"    Manual: Gfarm
.\"    Source: Gfarm
.\"  Language: English
.\"
.TH "GFHOST" "1" "20 Jan 2010" "Gfarm" "Gfarm"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gfhost \- Gfarm host maintenance command
.SH "SYNOPSIS"
.HP \w'\fBgfhost\fR\ 'u
\fBgfhost\fR [\-H | \-l | \-M] [\-iLprUv] [\-P\ \fIpath\fR] [\-a\ \fIarchitecture\fR] [\-D\ \fIdomain\-name\fR] [\-j\ \fIconcurrency\fR] [\fIhostname\fR...]
.HP \w'\fBgfhost\fR\ 'u
\fBgfhost\fR \-c [\-P\ \fIpath\fR] \-a\ \fIarchitecture\fR \-p\ \fIport\-number\fR [\-n\ \fInumber\-of\-CPUs\fR] \fIhostname\fR
.HP \w'\fBgfhost\fR\ 'u
\fBgfhost\fR \-m [\-P\ \fIpath\fR] [\-a\ \fIarchitecture\fR] [\-p\ \fIport\-number\fR] [\-n\ \fInumber\-of\-CPUs\fR] [\-A] \fIhostname\fR
.HP \w'\fBgfhost\fR\ 'u
\fBgfhost\fR \-d [\-P\ \fIpath\fR] \fIhostname\fR...
.HP \w'\fBgfhost\fR\ 'u
\fBgfhost\fR \-R [\-P\ \fIpath\fR]
.SH "DESCRIPTION"
.PP
\fBgfhost\fR
is used to display and maintain information about filesystem nodes\&. The function that
\fBgfhost\fR
performs is determined by an option, \-c, \-d, \-H, \-l, \-M, \-m, \-R\&. These functions are mutually exclusive, and only one option among them can be specified\&. If none of them is specified, host name will be displayed as the default function of
\fBgfhost\fR\&.
.SH "FUNCTIONS"
.PP
Metadata in the metadata server will be accessed by function \-c, \-d, \-M, \-m or \-R\&. These functions add/delete/display/modify/restore host information in the metadata\&.
.PP
If \-H, \-l or \-M is specified, or none of the functions are specified,
\fBgfhost\fR
displays filesystem node information\&. The \-M function only accesses information in the metadata server\&. Display functions other than \-M also access
\fBgfsd\fR, which is running on filesystem nodes\&. For functions which access
\fBgfhost\fR, the access option can be specified by options \-i, \-j, \-U and \-v\&.
.PP
You don\*(Aqt have to specify hostnames for display functions\&. In that case, all hosts which are registered in metadata will be displayed, but you can limit the type of hosts displayed by the \-a or \-D option\&. By default, hosts are displayed in alphabetical order, but you can change this by the \-L, \-p, or \-r options\&. Although the \-L option is ignored in the \-M function
and in the default function\&.
\&.
.PP
The following is a list of the functions of the
\fBgfhost\fR
command\&. You shouldn\*(Aqt specify more than one functions at a time\&.
.PP
<none>
.RS 4
If you don\*(Aqt specify any of the functions,
\fBgfhost\fR
accesses
\fBgfsd\fR, and displays the names of hosts which are currently available as its default function\&. Hostnames are displayed in alphabetical order, by default\&.
.RE
.PP
\fB\-c\fR
.RS 4
Creates the metadata information for the host that is specified in the argument\&. Option \-a is mandatory for this function, this option specifies the architecture of the host\&. Option \-p is mandatory in this function too, this option specifies the port number of
\fBgfsd\fR
on the host\&. Option \-n may be used to specify the number of CPUs of the host, and 1 CPU is assumed, if \-n is omitted\&.
.sp
You can specifiy multiple hostnames in this function\&. In that case, the first hostname is treated as the identifier of the host, and the host identifier is used for replication information management\&.
.RE
.PP
\fB\-d\fR
.RS 4
Deletes host information from metadata\&.
Currently, even hosts which are referred by replica catalog can be deleted\&. But be careful, because such deletions cause inconsistencies of metadata\&.
.RE
.PP
\fB\-H\fR
.RS 4
Displays load average and authentication method\&. With this function, the exact hostname passed by the gfhost command arguments will be displayed instead of the canonical host identifier\&. Also, this function displays the IP address used to access
\fBgfsd\fR
in parentheses just after the hostname\&.
.sp
If the host cannot be accessed due to a machine down or network problem, etc\&., x\&.xx/x\&.xx/x\&.xx will be displayed in the load average field\&. If the host is up, but
\fBgfsd\fR
on the host cannot be accessed, \-\&.\-\-/\-\&.\-\-/\-\&.\-\- will be displayed\&.
.sp
The next field is the authentication method used with the host\&. `G\*(Aq in this field means GSI authentication and encryption, `g\*(Aq means only authentication is performed by GSI and actual communication is unprotected plain data (gsi_auth), `s\*(Aq means gfarm sharedsecret authentication, `x\*(Aq means that the authentication failed, and `\-\*(Aq means that the authentication wasn\*(Aqt actually tried\&. If the \-U option is specified, this authentication method field won\*(Aqt be provided\&.
.sp
Hostnames are displayed in alphabetical order, by default\&.
.RE
.PP
\fB\-l\fR
.RS 4
Displays in the long format\&. This function displays both information retrieved from gfsd and the metadata server\&. The types of information retrieved from gfsd are load average and authentication method\&. And the types of information retrieved from the metadata server are architecture name, number of CPUs and host identifier\&. IP address will be displayed in parentheses just after the hostname used for the access to
\fBgfsd\fR\&.
.sp
If the host cannot be accessed due to a machine down or network problem, etc\&., x\&.xx/x\&.xx/x\&.xx will be displayed in the load average field\&. If the host is up, but
\fBgfsd\fR
on the host cannot be accessed , \-\&.\-\-/\-\&.\-\-/\-\&.\-\- will be displayed\&.
.sp
The next field is the authentication method used with the host\&. `G\*(Aq in this field means GSI authentication and encryption, `g\*(Aq means only authentication is performed by GSI and actual communication is unprotected plain data (gsi_auth), `s\*(Aq means gfarm sharedsecret authentication, `x\*(Aq means that the authentication failed, and `\-\*(Aq means that the authentication wasn\*(Aqt actually tried\&. If that \-U option is specified, this authentication method field won\*(Aqt be provided\&.
.sp
Hostnames are displayed in alphabetical order, by default\&.
.RE
.PP
\fB\-M\fR
.RS 4
The metadata information of the hosts will be displayed\&. Hostnames are displayed in alphabetical order, by default\&.
.RE
.PP
\fB\-m\fR
.RS 4
Modifies metadata information of the host, by specifying the host identifier\&. The \-a and \-n options overwrite the current value of each option\&.
.RE
.PP
\fB\-R\fR
.RS 4
Restores metadata information read from standard input\&. The format of the metadata is same as the format that the \-M function displays\&.
.RE
.PP
\fB\-?\fR
.RS 4
Prints usage\&.
.RE
.SH "OPTIONS"
.PP
\fB\-a\fR \fIarchitecture\fR
.RS 4
This option specifies the CPU architecture using a format like sparc\-sun\-solaris8 or i386\-redhat8\&.0\-linux, etc\&. If this option is used with the \-c or \-m function, this means the architecture used to add/modify the metadata information\&. If this option is used with \-H, \-l, \-M function or default function, this limits hosts to the specified architecture\&.
.RE
.PP
\fB\-D\fR \fIdomain\-name\fR
.RS 4
This option is used with the \-H, \-l, \-M function or the default function to limit hosts to the specified domain\&.
.RE
.PP
\fB\-i\fR
.RS 4
There is an "address_use" directive in %%SYSCONFDIR%%/gfarm2\&.conf and $HOME/\&.gfarm2rc to give priorities of network addresses for gfarm access\&. This directive works with the
\fBgfhost\fR
command, but will be ignored, if you specified the \-i option with
\fBgfhost\fR\&.
.RE
.PP
\fB\-j\fR \fIconcurrency\fR
.RS 4
This option specifies the concurrency used for access to
\fBgfsd\fR\&. The default value is 10\&.
.RE
.PP
\fB\-L\fR
.RS 4
Sorts by load average order\&. This option is effective only with the \-H and \-l functions
\&.
.RE
.PP
\fB\-n\fR \fInumber\-of\-CPUs\fR
.RS 4
This option is used with the \-c or \-m function, and specifies the number of CPUs of the host\&.
.RE
.PP
\fB\-p\fR \fIport\-number\fR
.RS 4
This option is used with \-c or \-m function, and specifies the port number of
\fBgfsd\fR
on the host\&.
.RE
.PP
\fB\-P\fR \fIpath\fR
.RS 4
This option specifies a pathname or a Gfarm URL to identify a metadata server which will be accessed by this command\&. If not specified, "/" is used as the default value\&.
.RE
.PP
\fB\-r\fR
.RS 4
Reverses the order of sort\&.
.RE
.PP
\fB\-u\fR
.RS 4
Plain order\&. This option stops sorting on the \-H, \-l, \-M function or the default function\&. With the \-M function, command argument order (if any), or the order that the metadata server answers is used for display\&. With the \-H, \-l function or the default function, the result is displayed in the order that each
\fBgfsd\fR
answers\&.
.RE
.PP
\fB\-U\fR
.RS 4
Suppresses authentication attempts by TCP, and only queries load average by UDP\&. This option only makes sense if you specified the \-H or \-l function, or if you didn\*(Aqt specify any function\&. This option makes the gfhost command run faster\&. If the \-H or \-l function is specified, this option makes the authentication method field disappear\&.
.RE
.PP
\fB\-v\fR
.RS 4
The \-H, \-l function and the default function don\*(Aqt produce error reports on
\fBgfsd\fR
accesses; these error reports will be produced by this option\&.
.RE
.SH "SEE ALSO"
.PP
\fBgfarm2.conf\fR(5),
\fBgfsd\fR(8)