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