.\" $HeadURL$ $LastChangedRevision$
.pso torc-config --format=man
.TH TORC 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
torc \- PPP reconnection daemon
.br
.ne 5
.SH SYNOPSIS
.B torc
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel\fR 
] 
[
.B \-f 
.I file
|
.B \-\-config\-file=\fIfile\fR
]
[
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
]
[
.B \-\-poll=\fIperiod\fR
]
[
.B \-n 
|
.B \-\-simulate
]
[
.B \-\-no\-fork
]
[
.B \-\-window=\fIHHMM\fB\-\fIHHMM\fR
]
[
.B \-\-disconnect=\fIHHMM\fR
]
[
.B \-\-interface=\fIpppinterface\fR
]
[
.B \-\-isp=\fIisp\fR
]
.br
.ne 5
.SH DESCRIPTION
.B Torc
was originally designed to overcome a problem experienced when using
.B pppd\fR(8)
with T-Online ISP, whereby 
.B pppd\fR(8)
would not attempt to automatically reconnect when, after twenty four
hours, T-Online broke the connection from their end. This problem is documented
as Debian bugs #127841 and #144146; bugs which have since been fixed. However, 
.B torc
has been enhanced and remains useful.
.PP
.B Torc
does two things; firstly it restarts
.B pppd\fR(8)
should it exit and, secondly, it does its best to keep the time at which
the connection is re-established to within a specified time window. This second
feature is intended to be used in conjunction with free fixed-name-to-dynamic-IP-address
translation services, to force the necessary IP address change to occur when 
most remote users of the system are sleeping.
.br
.ne 5
.SH CONFIGURATION
The configuration file, 
.B \*[torc_etc_prefix]/torc.conf\fR,
may specify the following directives. These may all be overridden by
command-line options.
.TP 25
.B enable: \fR[ \fB0\fR | \fB1\fR ]
.B Torc\fR,
itself, ignores this directive. It tolerates it in order that init.d
scripts may 
.B egrep\fR(1) 
for the directive in order to determine if they should invoke
.B torc
or not.
.TP
.B poll: \fIsecs\fR
Same as the
.B \-\-poll
command-line option.
.TP
.B fork: \fR[ \fB0\fR | \fB1\fR ]
If set to 
.B 0
then this is the same as using the 
.B \-\-no\-fork 
command-line option.
.TP
.B simulate: \fR[ \fB0\fR | \fB1\fR ]
If set to 
.B 1
then this is the same as using the
.B \-\-simulate
command-line option.
.TP 
.B window: \fIHHMM\fB\-\fIHHMM\fR
This is the same as the 
.B \-\-window 
command-line option.
.TP 
.B disconnect: \fIHHMM\fR
This is the same as the 
.B \-\-disconnect 
command-line option.
.TP 
.B interface: \fIpppinterface\fR
This is the same as the 
.B \-\-interface
command-line option.
.TP 
.B isp: \fIisp\fR
This is the same as the 
.B \-\-isp
command-line option.
.br
.ne 5
.SH OPTIONS
.TP 25
.B \-d \fIlevel\fR, \fB\-\-debug=\fIlevel\fR
Determines how verbose
.B torc
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP
.B \-f \fIfile\fR, \fB\-\-config\-file=\fIfile\fR
Specify an alternate config file. The default is
.B \*[torc_etc_prefix]/torc.conf\fR.
.TP
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-\-interface=\fIpppinterface\fR
specifies the name of the PPP interface to monitor. The default
is 
.B ppp0\fR.
.TP
.B \-\-isp=\fIisp\fR
specifies the name of the ISP, as would be specified when connection
with 
.B pon\fR(1).
.TP
.B \-n\fR, \fB\-\-simulate
prevents
.B torc
from actually manipulating the PPP connection. Instead it will
simulate modifying and checking the status of the connection by
creating or deleting and accessing the file 
.B \*[torc_tmp_prefix]/torc.simcon\fR.
.TP
.B \-\-no\-fork
stops 
.B torc
behaving like normal daemon process, and instead makes it run
in 'single-shot' mode. This is intended to make it callable
by
.B cron\fR(8).
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B torc
uses.
.TP 
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-\-poll=\fIperiod\fR
Sets the interval at which
.B torc
polls
.B pppd\fR(8). The default is 60 seconds.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.TP
.B \-\-window=\fIHHMM\fB\-\fIHHMM\fR
specifies the time window, within which if a PPP connection is established,
then it will not be scheduled for disconnection and reconnection. The
default is
.B 0500\-0600\fR.
.TP
.B \-\-disconnect=\fIHHMM\fR
specifies the time scheduled for disconnection and reconnection of a PPP 
connection established outside the time window. The default is 
.B 0501\fR.
.br
.ne 5
.SH EXIT STATUS
On success
.B torc
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP 25
.B \*[torc_etc_prefix]/torc.conf
The file may contain configuration settings, blank lines and hash-led 
comments. Configuration settings are colon-separated variables and 
values. The following variables may be used:
.B disconnect\fR,
.B interface\fR,
.B fork\fR,
.B poll\fR,
.B simulate\fR,
and
.B window\fR.
They correspond to the similarly named options mentioned above.
.TP 
.B \*[torc_tmp_prefix]/torc.simcon
This file is used to simulate the state of the PPP connection. It
may be created or deleted by the user or by
.B torc
itself.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
None.
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B torc\fR.
.br
.ne 5
.SH SEE ALSO
cron(8), pppd(8)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2003-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
.PP
This program 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.
.PP
This program 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.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.