usr.sbin/pppctl/pppctl.8

   1 .\" $FreeBSD: src/usr.sbin/pppctl/pppctl.8,v 1.12.2.8 2003/03/11 22:31:30 trhodes Exp $
   2 .Dd June 26, 1997
   3 .Os
   4 .Dt PPPCTL 8
   5 .Sh NAME
   6 .Nm pppctl
   7 .Nd PPP control program
   8 .Sh SYNOPSIS
   9 .Nm
  10 .Op Fl v
  11 .Op Fl t Ar n
  12 .Op Fl p Ar passwd
  13 .Xo Oo Ar host : Oc Ns
  14 .Ar Port | LocalSocket
  15 .Xc
  16 .Oo
  17 .Sm off
  18 .Ar command Oo ; Ar command Oc Ar ...
  19 .Sm on
  20 .Oc
  21 .Sh DESCRIPTION
  22 This utility provides command line control of the
  23 .Xr ppp 8
  24 daemon.  Its primary use is to facilitate simple scripts that
  25 control a running daemon.
  26 .Pp
  27 The
  28 .Nm
  29 utility is passed at least one argument, specifying the socket on which
  30 .Nm ppp
  31 is listening.  Refer to the
  32 .Sq set server
  33 command of
  34 .Nm ppp
  35 for details.  If the socket contains a leading '/', it
  36 is taken as an
  37 .Dv AF_LOCAL
  38 socket.  If it contains a colon, it is treated as a
  39 .Ar host : Ns Ar port
  40 pair, otherwise it is treated as a TCP port specification on the
  41 local machine (127.0.0.1).  Both the
  42 .Ar host
  43 and
  44 .Ar port
  45 may be specified numerically if you wish to avoid a DNS lookup
  46 or don't have an entry for the given port in
  47 .Pa /etc/services .
  48 .Pp
  49 All remaining arguments are concatenated to form the
  50 .Ar command Ns (s)
  51 that will be sent to the
  52 .Nm ppp
  53 daemon.  If any semi-colon characters are found, they are treated as
  54 .Ar command
  55 delimiters, allowing more than one
  56 .Ar command
  57 in a given
  58 .Sq session .
  59 For example:
  60 .Bd -literal -offset indent
  61 pppctl 3000 set timeout 300\\; show timeout
  62 .Ed
  63 .Pp
  64 Don't forget to escape or quote the ';' as it is a special character
  65 for most shells.
  66 .Pp
  67 If no
  68 .Ar command
  69 arguments are given,
  70 .Nm
  71 enters interactive mode, where commands are read from standard input.
  72 When reading commands, the
  73 .Xr editline 3
  74 library is used, allowing command-line editing (with
  75 .Xr editrc 5
  76 defining editing behaviour).  The history size
  77 defaults to
  78 .Em 20 lines .
  79 .Pp
  80 The following command line options are available:
  81 .Bl -tag -width Ds
  82 .It Fl v
  83 Display all data sent to and received from the
  84 .Nm ppp
  85 daemon.  Normally,
  86 .Nm
  87 displays only non-prompt lines received.  This option is ignored in
  88 interactive mode.
  89 .It Fl t Ar n
  90 Use a timeout of
  91 .Ar n
  92 instead of the default 2 seconds when connecting.  This may be required
  93 if you wish to control a daemon over a slow (or even a dialup) link.
  94 .It Fl p Ar passwd
  95 Specify the password required by the
  96 .Nm ppp
  97 daemon.  If this switch is not used,
  98 .Nm
  99 will prompt for a password once it has successfully connected to
 100 .Nm ppp .
 101 .El
 102 .Sh EXAMPLES
 103 If you run
 104 .Nm ppp
 105 in
 106 .Fl auto
 107 mode,
 108 .Nm
 109 can be used to automate many frequent tasks (you can actually control
 110 .Nm ppp
 111 in any mode except interactive mode).  Use of the
 112 .Fl p
 113 option is discouraged (even in scripts that aren't readable by others)
 114 as a
 115 .Xr ps 1
 116 listing may reveal your secret.
 117 .Pp
 118 The best way to allow easy, secure
 119 .Nm
 120 access is to create a local server socket in
 121 .Pa /etc/ppp/ppp.conf
 122 (in the correct section) like this:
 123 .Bd -literal -offset indent
 124 set server /var/run/internet "" 0177
 125 .Ed
 126 .Pp
 127 This will instruct
 128 .Nm ppp
 129 to create a local domain socket, with srw------- permissions and no
 130 password, allowing access only to the user that invoked
 131 .Nm ppp .
 132 Refer to the
 133 .Xr ppp 8
 134 man page for further details.
 135 .Pp
 136 You can now create some easy-access scripts.  To connect to the internet:
 137 .Bd -literal -offset indent
 138 #! /bin/sh
 139 test $# -eq 0 && time=300 || time=$1
 140 exec pppctl /var/run/internet set timeout $time\\; dial
 141 .Ed
 142 .Pp
 143 To disconnect:
 144 .Bd -literal -offset indent
 145 #! /bin/sh
 146 exec pppctl /var/run/internet set timeout 300\\; close
 147 .Ed
 148 .Pp
 149 To check if the line is up:
 150 .Bd -literal -offset indent
 151 #! /bin/sh
 152 pppctl -p '' -v /var/run/internet quit | grep ^PPP >/dev/null
 153 if [ $? -eq 0 ]; then
 154   echo Link is up
 155 else
 156   echo Link is down
 157 fi
 158 .Ed
 159 .Pp
 160 You can even make a generic script:
 161 .Bd -literal -offset indent
 162 #! /bin/sh
 163 exec pppctl /var/run/internet "$@"
 164 .Ed
 165 .Pp
 166 You could also use
 167 .Nm
 168 to control when dial-on-demand works.  Suppose you want
 169 .Nm ppp
 170 to run all the time, but you want to prevent dial-out between 8pm and 8am
 171 each day.  However, any connections active at 8pm should continue to remain
 172 active until they are closed or naturally time out.
 173 .Pp
 174 A
 175 .Xr cron 8
 176 entry for 8pm which runs
 177 .Bd -literal -offset indent
 178 pppctl /var/run/internet set filter dial 0 deny 0 0
 179 .Ed
 180 .Pp
 181 will block all further dial requests, and the corresponding 8am entry
 182 .Bd -literal -offset indent
 183 pppctl /var/run/internet set filter dial -1
 184 .Ed
 185 .Pp
 186 will allow them again.
 187 .Sh ENVIRONMENT
 188 The following environment variables are understood by
 189 .Nm
 190 when in interactive mode:
 191 .Bl -tag -width XXXXXXXXXX
 192 .It Dv EL_SIZE
 193 The number of history lines.  The default is 20.
 194 .It Dv EL_EDITOR
 195 The edit mode.  Only values of "emacs" and "vi" are accepted.  Other values
 196 are silently ignored.  This environment variable will override the
 197 .Ar bind -v
 198 and
 199 .Ar bind -e
 200 commands in
 201 .Pa ~/.editrc .
 202 .El
 203 .Sh SEE ALSO
 204 .Xr ps 1 ,
 205 .Xr editline 3 ,
 206 .Xr editrc 5 ,
 207 .Xr services 5 ,
 208 .Xr ppp 8
 209 .Sh HISTORY
 210 The
 211 .Nm
 212 utility first appeared in
 213 .Fx 2.2.5 .