path: root/usr.sbin/ppp/pppctl/pppctl.8

.\"	$OpenBSD: pppctl.8,v 1.17 2011/05/02 11:14:11 jmc Exp $
.\"
.\" Copyright (c) 1997 Brian Somers <brian@Awfulhak.org>
.\" All rights reserved.
.\"
.\" 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.
.\"
.Dd $Mdocdate: May 2 2011 $
.Dt PPPCTL 8
.Os
.Sh NAME
.Nm pppctl
.Nd PPP control program
.Sh SYNOPSIS
.Nm pppctl
.Bk -words
.Op Fl v
.Op Fl p Ar passwd
.Op Fl t Ar n
.Xo
.Oo Ar host : Oc Ar port |
.Ar LocalSocket
.Xc
.Op Ar command Op ; Ns Ar command ...
.Ek
.Sh DESCRIPTION
This program provides command line control of the
.Xr ppp 8
daemon.
Its primary use is to facilitate simple scripts that
control a running daemon.
.Pp
.Nm
is passed at least one argument, specifying the socket on which
.Xr ppp 8
is listening.
Refer to the
.Ic set server
command of
.Xr ppp 8
for details.
If the socket contains a leading
.Sq / ,
it is taken as an
.Dv AF_LOCAL
socket.
If it contains a colon, it is treated as a
.Ar host : Ns Ar port
pair, otherwise it is treated as a TCP port specification on the
local machine (127.0.0.1).
Both the
.Ar host
and
.Ar port
may be specified numerically if you wish to avoid a DNS lookup
or don't have an entry for the given port in
.Pa /etc/services .
.Pp
All remaining arguments are concatenated to form the command(s)
that will be sent to the
.Xr ppp 8
daemon.
If any semi-colon characters are found, they are treated as
.Ar command
delimiters, allowing more than one
.Ar command
in a given
.Dq session .
For example (adding a route):
.Bd -literal -offset indent
pppctl 3000 add 192.168.1.0 255.255.255.0 127.0.0.1\e; show route
.Ed
.Pp
Don't forget to escape or quote the
.Sq \&;
as it is a special character for most shells.
.Pp
If no
.Ar command
arguments are given,
.Nm
enters interactive mode, where commands are read from standard input.
When reading commands, the
.Xr editline 3
library is used, allowing command-line editing (with
.Xr editrc 5
defining editing behaviour).
The history size defaults to 20 lines.
.Pp
The following command line options are available:
.Bl -tag -width "-p passwd  "
.It Fl p Ar passwd
Specify the password required by the
.Xr ppp 8
daemon.
If this switch is not used,
.Nm
will prompt for a password once it has successfully connected to
.Xr ppp 8 .
.It Fl t Ar n
Use a timeout of
.Ar n
instead of the default 2 seconds when connecting.
This may be required
if you wish to control a daemon over a slow (or even a dialup) link.
.It Fl v
Display all data sent to and received from the
.Xr ppp 8
daemon.
Normally,
.Nm
displays only non-prompt lines received.
This option is ignored in interactive mode.
.El
.Sh ENVIRONMENT
The following environment variables are understood by
.Nm
when in interactive mode:
.Bl -tag -width XXXXXXXXXX
.It Ev EL_SIZE
The number of history lines.
The default is 20.
.It Ev EL_EDITOR
The edit mode.
Only values of
.Dq emacs
and
.Dq vi
are accepted.
Other values are silently ignored.
This environment variable will override the
.Dq bind -v
and
.Dq bind -e
commands in
.Pa ~/.editrc .
.El
.Sh EXAMPLES
If you run
.Xr ppp 8
in
.Fl auto
mode,
.Nm
can be used to automate many frequent tasks (you can actually control
.Xr ppp 8
in any mode except interactive mode).
Use of the
.Fl p
option is discouraged (even in scripts that aren't readable by others)
as a
.Xr ps 1
listing may reveal your secret.
.Pp
The best way to allow easy, secure
.Nm
access is to create a local server socket in
.Pa /etc/ppp/ppp.conf
(in the correct section) like this:
.Bd -literal -offset indent
set server /var/run/internet "" 0177
.Ed
.Pp
This will instruct
.Xr ppp
to create a local domain socket, with srw------- permissions and no
password, allowing access only to the user that invoked
.Xr ppp .
Refer to the
.Xr ppp 8
man page for further details.
.Pp
You can now create some easy-access scripts.
To connect to the Internet:
.Bd -literal -offset indent
#! /bin/sh
test $# -eq 0 && time=300 || time=$1
exec pppctl /var/run/internet set timeout $time\e; dial
.Ed
.Pp
To disconnect:
.Bd -literal -offset indent
#! /bin/sh
exec pppctl /var/run/internet set timeout 300\e; close
.Ed
.Pp
To check if the line is up:
.Bd -literal -offset indent
#! /bin/sh
pppctl -p '' -v /var/run/internet quit | grep ^PPP >/dev/null
if [ $? -eq 0 ]; then
  echo Link is up
else
  echo Link is down
fi
.Ed
.Pp
You can even make a generic script:
.Bd -literal -offset indent
#! /bin/sh
exec pppctl /var/run/internet "$@"
.Ed
.Sh SEE ALSO
.Xr ps 1 ,
.Xr editline 3 ,
.Xr editrc 5 ,
.Xr services 5 ,
.Xr ppp 8
.Sh HISTORY
The
.Nm
command first appeared in
.Fx 2.2.5 .