usr.sbin/pppctl/pppctl.8

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