Build: Fix construction of manual pages.

[tripe] / client / tripectl.1.in

.\" -*-nroff-*-
.\".
.\" Manual for the administration client
.\"
.\" (c) 2008 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Trivial IP Encryption (TrIPE).
.\"
.\" TrIPE is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" TrIPE is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with TrIPE; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"--------------------------------------------------------------------------
.so ../common/defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH tripectl 1 "19 February 2001" "Straylight/Edgeware" "TrIPE: Trivial IP Encryption"
.
.\"--------------------------------------------------------------------------
.SH "NAME"
.
tripectl \- simple client for TrIPE
.
.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
.
.B tripectl
.RB [ \-w ]
.RB [ \-\fIoptions ]
.RI [ command
.RI [ args ]...]
.br
.B tripectl
.RB [ \-Dl ]
.RB [ \-f
.IR file ]
.RB [ \-\fIoptions ]
.PP
Options:
.br
	\&
.RB [ \-s ]
.RB [ \-d
.IR dir ]
.RB [ \-a
.IR socket ]
.RB [ \-P
.IR pidfile ]
.br
	\&
.RB [ \-p
.IR path ]
.RB [ \-U
.IR user ]
.RB [ \-G
.IR group ]
.RB [ \-S
.IB arg , arg ,\fR...]
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B tripectl
program is a simple client which can be used, either interactively or
from a script, to send commands to and read status information from a
running
.BR tripe (8)
server.  It can also be used to start
.BR tripe (8),
passing appropriate arguments and capturing logging information.
.SS "Command-line options"
.TP
.B "\-h, \-\-help"
Writes a brief description of the command-line options available to
standard output and exits with status 0.
.TP
.B "\-v, \-\-version"
Writes tripe's version number to standard output and exits with status
0.
.TP
.B "\-u, \-\-usage"
Writes a brief usage summary to standard output and exits with status 0.
.TP
.B "\-D, \-\-daemon"
Makes
.B tripectl
disassociate from the terminal and become a background process after
connecting to the server.
.TP
.BI "\-d, \-\-directory=" dir
Make
.I dir
the current directory, before doing anything else.  Note that all the
other filenames (e.g., the log output file) are relative to this
directory.  The default directory, if this option is not specified, is
taken from the environment variable
.BR TRIPEDIR ;
if that's not defined either, a default default of
.B "\*(/c"
is used.
.TP
.BI "\-a, \-\-admin-socket=" socket
If connecting to a running server, connect to the socket named
.IR socket ;
if running a new server, instruct it to listen for admin
connections on
.IR socket .
The default socket, if this option is not specified, is taken from the
environment variable
.BR TRIPESOCK ;
if that's not defined either, a default default of
.B "\*(/s/tripesock"
is used.
.TP
.BI "\-P, \-\-pidfile=" pidfile
Write
.BR tripectl 's
process-id to
.I pidfile
(relative to
.IR dir ).
If the
.B \-D
and
.B \-f
options are given, a default of
.IB dir /tripectl.pid
is used if you don't give a
.B \-P
option.
.TP
.B "\-s, \-\-spawn"
Start a new server: don't connect to an existing one.  Starting a
.BR tripe (8)
server in this manner is a good way to ensure that no log messages are
lost.  The
.BR \-l ,
.B \-f
and
.B \-D
options are particularly useful in conjunction with
.BR \-s .
.TP
.BI "\-p, \-\-spawn\-path=" path
Implies
.BR \-s ;
runs the program named by
.I path
rather than the default
.BR tripe .
If
.I path
is actually an unqualified filename, the program to run is found using
the
.B PATH
environment variable in the usual way.
.TP
.BI "\-S, \-\-spawn\-args=" arg , arg ,\fR...
Implies
.BR \-s ;
passes the comma-separated
.IR arg s
to the
.B tripe
server on its command line.  Arguments added using this option are added
.I after
any passed automatically by
.B tripectl
(e.g.,
.BR \-a ).
.TP
.BI "\-U, \-\-setuid=" user
Set uid to that of
.I user
(either a user name or integer uid) after initialization.  Also set gid
to
.IR user 's
primary group, unless overridden by a
.B \-G
option.  If a new
.BR tripe (8)
server is going to be spawned then it is also passed corresponding
.B \-U
and
.B \-G
options.
.TP
.BI "\-G, \-\-setgid=" group
Set gid to that of
.I group
(either a group name or integer gid) after initialization.  If a new
.BR tripe (8)
server is going to be spawned then it is also passed a corresponding
.B \-G
option.
.TP
.B "\-l, \-\-syslog"
Send warnings and trace messages to the
.BR syslog (8)
service.  Messages are logged using the
.B daemon
facility.  Warnings are logged with severity
.BR warning ;
trace messages are logged with severity
.BR debug .
.TP
.BI "\-f, \-\-logfile=" file
Write warnings and trace messages to
.IR file .
On receipt of a
.B SIGHUP
signal,
.B tripectl
will close its log file and reopen a new one with the same name.  This
is useful when you rotate logs.
.TP
.B "\-w, \-\-warnings"
Write warnings to standard error even when running noninteractively.
.SS "Interactive use"
With no arguments,
.B tripectl
will connect to a running server and await commands from its standard
input.  The commands are submitted to the server unchanged, and the
results written to standard output.  It will quit when it receives a
fatal signal or an end-of-file indication from the server.
.SS "Use from scripts"
If arguments are given to
.BR tripectl ,
they are quoted if necessary to protect spaces and other special
characters, concatenated with spaces between, and submitted to the
server after connection.  Any
.B INFO
responses returned by the server are written to standard output (without
the
.B INFO
on the front).  A
.B FAIL
response causes the error message to be written to standard error, and
the client to exit with a nonzero return code.  An
.B OK
response causes the client to exit with a zero return code.  Unless the
.B \-w
command-line option was given, any
.B WARN
responses are discarded; if
.B \-w
.I was
given,
.B WARN
responses are written to standard error.  In all cases,
.B TRACE
responses are ignored.
.SS "Starting the tripe server"
If any of the options
.BR \-s ,
.B \-p
or
.B \-S
are given,
.B tripectl
will start a new
.B tripe
server, rather than connecting to an existing one.
.PP
The command line for the new server is
.IP
.I path
.B \-F
.B \-d.\&
.B \-a
.I socket
.I dash-S-options
.PP
where
.I dash-S-options
is the concatenation of the arguments of
.B \-S
options, split at commas.
.PP
Starting a
.B tripe
server through
.B tripectl
is most useful if you want to collect logging information from the
server, and want to avoid losing any.  For example, the command
.VS
tripectl -Ds -f tripe.log
.VE
starts up a new server in the default directory, and captures all of its
logging output (i.e.,
.B WARN
and
.B TRACE
messages) in the file
.BR tripe.log .
It stores its process-id in
.BR tripectl.pid .
.PP
It's possible to communicate interactively with a newly-started server,
or to give it a command and quit, but this is seldom useful.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR tripe\-admin (5),
.BR tripe (8).
.PP
.IR "The Trivial IP Encryption Protocol" ,
.IR "The Wrestlers Protocol" .
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------