.\"
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
.\"
.\" Copyright 2020 John-Mark Gurney
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.\" Note: The date here should be updated whenever a non-trivial
.\" change is made to the manual page.
.Dd October 25, 2020
.Dt GGATESSH 7
.Os
.Sh NAME
.Nm ggatessh
.Nd start up script for ggatessh
.Sh SYNOPSIS
.Bd -literal -compact
service ggatessh [one]start [ <devnum> ... ]
service ggatessh [one]rescue [ <devnum> ... ]
service ggatessh [one]stop [ <devnum> ... ]
service ggatessh [one]destroy [ <devnum> ... ]
service ggatessh [one]status [ <devnum> ... ]
.Ed
.Pp
Configuration via
.Xr rc.conf 5 :
.Dl ggatessh_enable="YES"
.Dl ggatessh_devs="<listofnums>"
.Dl ggatessh_<num>_path="usera@hosta:patha/to/file"
.Dl ggatessh_<num>_pidfile="/path/to/pidfile"
.Dl ggatessh_<num>_sector="<size of sector>"
.Dl ggatessh_<num>_port="<port of server>"
.Dl ggatessh_<num>_sshkey="/path/to/ssh/key"
.Sh DESCRIPTION
The
.Nm
rc.d script is allows for boot time and run time configuration of
.Xr ggatessh 8 .
.Pp
If no
.Ar devnum
arguments are specified, then the script iterates through all the
numbers that are specified in the
.Dv ggatessh_devs
variable.
If one or more
.Ar devnum
arguments are specified, the provided commands is run for each of them.
.Pp
The following actions are:
.Bl -tag -width destroy
.It start
This creates the ggate device and runs the daemon with the specified
parameters.
.It rescue
This requires that the ggate device has already been created w/ the
.Cm start
command or via another mechanism.
This command will run
.Xr ggatessh 8
with the rescue command, allowing IOs to resume after a previous
daemon has died.
.It stop
This command will kill the daemon that was started via the
.Cm start
command.
This will not destroy the ggate device, which means that any IO to
the device will hang and not be completed until the daemon is restarted
or the device is forcefully destroyed using the
.Xr ggatessh 8
command.
.It destroy
This will destroy the ggate device.
If the device is busy, or currently open, it will fail.
.It status
Print out the status of the
.Xr ggatessh 8
daemon, and if it is running, its pid.
.El
.Pp
For each
.Ar devnum
specified, either via
.Dv ggatessh_devs
or as an argument, the following
.Xr rc.conf 5
options are used:
.Bl -tag -width "ggatessh_<num>_pidfile"
.It ggatessh_<num>_path
This specifies the user, host and file to use.
Its format is:
.Dv [user@]host:file .
If the user part is not specified, it defaults to
.Dv root.
.It ggatessh_<num>_pidfile
Specify the file to use to store the daemon's pid.
If this is not specified, it defaults to
.Pa /var/run/ggatessh.ggate<num>.pid .
.It ggatessh_<num>_sector
Specifies the sector size of the device.
If not specified, the default,
.Dv 4096
is used.
.It ggatessh_<num>_port
Specifies the port to connect to on the host.
The default is 22 if not specified.
.It ggatessh_<num>_sshkey
Specifies the ssh key to use for authentication.
If unspecified, the default
.Pa $HOME/.ssh/id_rsa
is used.
As
.Dv $HOME
may be different when the startup script is run in different contexts,
it is highly recommended to specify this.
.El
.Sh FILES
.Bl -tag -width ".Pa /dev/null" -compact
.It Pa /etc/rc.d/ggatessh
The script described in this man page.
.El
.Sh SEE ALSO
.Xr rc.conf 5 ,
.Xr ggatessh 8
.Sh HISTORY
The
.Nm
script first appeared in
.Fx 13.0 .
.Sh AUTHORS
This manual page was written by
.An John-Mark Gurney Aq Mt jmg@FreeBSD.org .