freebsd-dev/usr.sbin/pppctl/pppctl.8

.\" $Id: pppctl.8,v 1.3 1997/09/29 19:11:45 wosch Exp $
.Dd 26 June 1997
.Os FreeBSD
.Dt PPPCTL 8
.Sh NAME
.Nm pppctl
.Nd
PPP control program
.Sh SYNOPSIS
.Nm
.Op Fl v
.Op Fl t Ar n
.Op Fl p Ar passwd
.Ar [host:]Port | LocalSocket
.Ar command
.Op Ar ;command
.Ar ...
.Sh DESCRIPTION
This program provides command line control of the
.Nm ppp
daemon.  Its primary use is to facilitate simple scripts that
control a running daemon.

.Nm Pppctl
expects at least two arguments.  The first is interpreted as the
socket on which the
.Nm ppp
daemon is listening.  If the socket contains a leading '/', it
is taken as an AF_LOCAL socket.  If it contains a colon, it is
treated as a host:port pair, otherwise it is treated as just a
port specification on the local machine (127.0.0.1).  Both the
host and 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
.Nm ppp
daemon.  If any semi-colon characters are found, they are treated
as command delimiters, allowing more than one command in a given
"session".  For example;

  pppctl 3000 set timeout 300\\; show timeout

Don't forget to escape or quote the ';' as it is a special character
for most shells.

The following command line options are available:
.Bl -tag -width Ds
.It Fl v
Display all data sent to and received from the
.Nm ppp
daemon.  Normally,
.Nm pppctl
displays only non-prompt lines received.
.It Fl t Ar n
Use a timeout of
.Ar n
instead of the default 2 seconds.  This may be required if you
wish to control a daemon over a slow (or even a dialup) link.
.It Fl p Ar passwd
Specify the password required by the
.Nm ppp
daemon.  If this switch is not used,
.Nm
will prompt for a password once it has successfully connected to
.Nm ppp .
.El

.Sh EXAMPLES
Assuming you want to run
.Nm ppp
in
.Fl auto
mode, 
.Nm
can be used to automate many frequent tasks.  Use of the
.Fl p
option is discouraged (even in scripts that aren't readably by others)
as a
.Xr ps 1
listing may reveal your secret.
.Pp
In order to have
.Nm ppp
create a socket for use with
.Nm pppctl ,
you will need to define a password for your local system:
.Bd -literal -offset indent
# touch /etc/ppp/ppp.secret
# chown root.wheel /etc/ppp/ppp.secret
# chmod 400 /etc/ppp/ppp.secret
# echo "`hostname -s` MyPassword" >>/etc/ppp/ppp.secret
.Ed

.Pp
The most secure way to allow easy, secure
.Nm
access, and to make sure you can distinguish between multiple invocations
of
.Nm ppp
is to create a local server socket in
.Pa /etc/ppp/ppp.conf
(in the correct section):

.Bd -literal -offset indent
set server /var/run/internet 0666
.Ed

This will instruct
.Nm ppp
to create a local domain socket rather than the tcp socket that's created
by default.  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 -t 60 /var/run/internet set timeout $time\\; dial
.Ed

.Pp
To disconnect:
.Bd -literal -offset indent
#! /bin/sh
exec pppctl /var/run/internet set timeout 300\\; close
.Ed

.Pp
To check if the line is up:
.Bd -literal -offset indent
#! /bin/sh
pppctl -p '' -v /var/run/internet '' | 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 services 5 ,
.Xr ppp 8

.Sh HISTORY
The
.Nm
command first appeared in FreeBSD 2.2.5.