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