f5gs.8.in

.\"
.\" Please read 'man 7 groff_man' howto use various macros.
.TH F5GS "8" "@PACKAGE_BUILD_DATE@" "@PACKAGE_STRING@" "System Administration"
.SH NAME
f5gs \- F5 graceful scaling helper daemon
.SH SYNOPSIS
.B f5gs
[options]
.SH DESCRIPTION
In the beginning this daemon was thought to be only an additional health
check for load balanced server to allow easy way to disable them from
server side.  Later the scope of the software has changed, and the f5gs
status are been seen as more generic expression of should the server
receive traffic, be monitored, or be part of automation in general.
.PP
This daemon will listen a TCP port
.BR @F5GS_TCP_PORT@ .
All connections to that port will be replied with one of the following
responses:
.IR disable ,
.IR maintenance ,
.IR enable ,
or
.IR unknown .
Run status is wrote to a file, where it is retrieved at daemon start up.
The run status files are wrote to a directory that can contain multiple
files, identified by listen address and tcp port.  This allows having
several
.B f5gs
instances running in same server.
.PP
The
.I unknown
cannot be set.  It stands for health check status that is never set.
From external observers point of view
.I unknown
and
.I disable
status should be seen as the same.
.PP
The daemon will wait client for one second to submit something.  Almost
any input is ignored, with exception of string
.B info:1
that makes server to send time stamp of most recent status change and
reason if the previous change had one.
.SH OPTIONS
.TP
\fB\-d\fR, \fB\-\-disable\fR
Disable the health check.  This will stop new connections to arrive, and
shut old connections immediately.
.TP
\fB\-m\fR, \fB\-\-maintenance\fR
Use health check to quiesce connections.  This will stop new connections
to arrive, while the existing connections are served.
.TP
\fB\-e\fR, \fB\-\-enable\fR
Enable health check.  This will set the service to normal operational
status.
.TP
\fB\-s\fR, \fB\-\-server\fR
Start the health check daemon.  The daemon tries to find old service
status file, and set the initial status to what is used to be.  If any of
the status change options is used with \-\-service option the option will
override contents of the old status file.
.TP
\fB\-a\fR, \fB\-\-address\fR \fIaddress\fR
Bind the server to
.IR address .
When the
.I address
is defined without \-\-server option status will be requested from the
.IR address .
Address can be IP or a DNS name.  The default address is
.IR 0.\:0.\:0.\:0 ,
that binds the server to all interface or send the request to localhost.
.TP
\fB\-p\fR, \fB\-\-port\fR \fIport\fR
TCP
.I port
of the server.  Default port is
.IR @F5GS_TCP_PORT@ .
.TP
\fB\-\-statedir\fR \fIdirectory\fR
Relocate the command status
.I directory
to elsewhere from
.IR @f5gs_rundir@ .
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Do not print anything, but inform with an exit value below what is the
status.  This option is applicable only when running in client mode, and
is meant to be used in scripts.
.PP
.RS
.PD 0
.TP
.B 0
enable
.TP
.B 1
maintenance
.TP
.B 2
disable
.TP
.B 3
unknown, or an error while determining the status such as f5gs server not
running
.PD
.RE
.TP
\fB\-\-reason\fR=\fItext\fR
Add reason text to state change.  The text is meant for human consumption.
.TP
\fB\-\-why\fR
Request reason why the current state is set.  The output will always
contain timestamp information when the program state has last time
altered.  The timestamp can persist over system reboots, as long the
state file is intact.
.TP
\fB\-\-no\-scripts\fR
Skip running pre or post scripts at status change.
.TP
\fB\-\-force\fR
Run pre and post scripts, but ignore their return values.
.TP
\fB\-\-foreground\fR
Run server process in foreground with result an operator can see error
messages from terminal rather than syslog or journal.  This option is
useful only when debugging.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version information, and what compile modules are in use, and
exit.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display help and exit.
.SH EXAMPLE
f5gs \-\-server
.br
f5gs \-\-enable
.br
F5GS="additional instruction" f5gs \-\-enable
.br
f5gs
.br
f5gs \-\-quiet; echo $?
.br
echo hello | nc server.example.com @F5GS_TCP_PORT@; echo
.br
f5gs \-\-why \-\-address server.example.com
.SH BUGS
Please report to author if you find a bug.
.PP
Lack of daemon stop functionality is known quirk, and done on purpose.
If a host needs this service you will never want to stop the service,
disabling is as good as stopping.  If you really want stop you should
kill the process.
.SH SYSTEMD INTEGRATION
When compiled with systemd support the
.B f5gs
will use socket actication.  The message that usually are sent to syslog
are using journald native integration.  Message ID fields that are in use
are
.TS
tab(^);
l l.
e7237db848ae4091b5ce09b2ebb75944^errors^
74605f2715d34b018a2c61c37a994c7b^status changes^
f5eb95b2817e4669a8cc40ea839411b3^stop or start^
.TE
.SH LICENSE
The f5gs has BSD 2-clause license which also known as "Simplified BSD
License" or "FreeBSD License".
.SH FILES
.TP
.B @f5gs_pre@
An executable that is ran before status change is sent.  If a return
value of the executable is not success
.RB ( 0 )
the status change is cancelled.  The executable will receive same command
line options and arguments as the original
.BR f5gs .
See
.I @datadir@/f5gs/pre-script
for an example how to write a script like this.
.TP
.B @f5gs_post@
An executable that is ran after status change is sent.  Return value of
the executable is ignored.  For the rest see pre script above.
.BR f5gs .
.TP
.B @f5gs_rundir@
Location of the status files.
.SH ENVIRONMENT
When
.B F5GS
is set it is forwarded as-is to
.I pre
and
.I post
executables.
.B PATH
is hardcoded to have _PATH_STDPATH value from paths.h header file, that
usually has value
.I /usr/bin:\:/bin:\:/usr/sbin:\:/sbin
All other environment variables are cleared.
.SH AUTHORS
.MT @PACKAGE_BUGREPORT@
@PACKAGE_MAINTAINER@
.ME
.SH "SEE ALSO"
.BR systemd (1),
.BR journalctl (1),
.BR tcpdump (1),
.UR https://\:devcentral.\:f5.com\:/articles\:/f5-friday-gracefully-scaling-down
F5 Friday: Gracefully Scaling Down
.UE .
.SH AVAILABILITY
.UR @PACKAGE_URL@
.UE