usr.sbin/pppctl/pppctl.8

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