← Back to branch summary

~ubuntu-branches/ubuntu/maverick/wpasupplicant/maverick

« back to all changes in this revision

Viewing changes to debian/wpa_action.8

  • Committer: Bazaar Package Importer
  • Author(s): Kel Modderman
  • Date: 2006-10-05 08:04:01 UTC
  • mfrom: (1.2.1 upstream) (2.1.14 edgy)
  • Revision ID: james.westby@ubuntu.com-20061005080401-myfwjtq7di70dyeo
http://bugs.debian.org/388316
* Update madwifi headers to latest SVN. (Closes: #388316)
* Remove failed attempt at action locking. [debian/functions.sh,
  debian/wpa_action.sh]
* Add hysteresis checking functions, to avoid "event loops" while
  using wpa-roam. [debian/functions.sh, debian/wpa_action.sh]
* Change of co-maintainer email address.
* Add ishex() function to functions.sh to determine wpa-psk value type in
  plaintext or hex. This effectively eliminates the need for the bogus and
  somewhat confusing wpa-passphrase contruct specific to our scripts and
  allows wpa-psk to work with either a 8 to 63 character long plaintext
  string or 64 character long hex string.
* Adjust README.modes to not refer to the redundant wpa-passphrase stuff.
* Add big fat NOTE about acceptable wpa-psk's to top of example gallery.
* Strip surrounding quotes from wpa-ssid if present, instead of just whining
  about them.
* Update email address in copyright blurb of functions.sh, ifupdown.sh and
  wpa_action.sh.  

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/wpa_action.8
 
1
.TH WPA_ACTION "8" "26 May 2006" "" ""
 
2
.SH NAME
 
3
wpa_action \- wpa_cli action script
 
4
.SH SYNOPSIS
 
5
\fBwpa_action\fR \fIIFACE ACTION\fR
 
6
.SH "DESCRIPTION"
 
7
\fBwpa_action\fR is a shell script designed to control the \fBifupdown\fR
 
8
framework according to \fIACTION\fR events received from \fBwpa_supplicant\fR.
 
9
\fBwpa_cli\fR receives \fICONNECTED\fR and \fIDISCONNECTED\fR events from
 
10
\fBwpa_supplicant\fR via the crtl_iface socket and gives the \fIACTION\fR event
 
11
to the \fBwpa_action\fR script as an argument, along with the \fIIFACE\fR to be
 
12
acted upon.
 
13
.PP
 
14
\fBwpa_action\fR also receives an environment variable from \fBwpa_cli\fR,
 
15
\fIWPA_ID_STR\fR, containing an alphanumeric identification string for the
 
16
\fICURRENT\fR network block. \fIWPA_ID_STR\fR is provided by the 'id_str'
 
17
network block option of \fBwpa_supplicant.conf\fR, and provides a means to map
 
18
the \fIACTION\fR to a \fILOGICAL\fR interface configured in the \fBinterfaces\fR
 
19
file.
 
20
.PP
 
21
If either the ifupdown \fBinterfaces\fR or \fIifstate\fR file cannot be found,
 
22
\fBwpa_action\fR will exit silently (status 0). \fBwpa_action\fR will search
 
23
the following locations for their existance:
 
24
.nf
 
25
        /etc/network/run/ifstate
 
26
        /var/run/network/ifstate
 
27
        /etc/network/interfaces
 
28
.ni
 
29
.PP
 
30
.SH IFACE
 
31
Network interface to be acted upon, for example 'eth1' or 'wlan0'.
 
32
.SH ACTION
 
33
An \fIACTION\fR to be performed on the \fIIFACE\fR.
 
34
.TP
 
35
\fBCONNECTED\fR
 
36
\fBwpa_supplicant\fR has completed authentication.
 
37
\fBifup\fR \fIIFACE=WPA_ID_STR\fR is invoked and the action is logged to
 
38
\fI/var/log/wpa_action.log\fR. Network settings for the \fILOGICAL\fR
 
39
interface \fIWPA_ID_STR\fR are applied.
 
40
.TP
 
41
\fBDISCONNECTED\fR
 
42
\fBwpa_supplicant\fR has detected disconnection.
 
43
\fBifdown\fR \fIIFACE=WPA_ID_STR\fR is invoked and the action is logged to
 
44
\fI/var/log/wpa_action.log\fR. Network settings for the \fILOGICAL\fR
 
45
interface \fIWPA_ID_STR\fR are undone.
 
46
.TP
 
47
\fBstop\fR
 
48
The 'stop' \fIACTION\fR is a called manually by the user, to stop the 
 
49
\fBwpa_cli\fR daemon, invoke \fBifdown\fR \fIIFACE\fR (if the \fIIFACE\fR is
 
50
present in the \fIifstate\fR file) and stop the \fBwpa_supplicant\fR daemon.
 
51
The action is logged to \fI/var/log/wpa_action.log\fR. 'down' is a
 
52
synonym for 'stop' and can be used equally.
 
53
.TP
 
54
\fBreload\fR
 
55
The 'reload' \fIACTION\fR can be used to reload the \fBwpa_supplicant\fR
 
56
configuration file specified by \fIwpa-roam\fR . 'restart' is a synonym 
 
57
for 'reload' and can be used equally. The action is logged to
 
58
\fI/var/log/wpa_action.log\fR.
 
59
.SH ENVIRONMENT
 
60
An alphanumeric identification string provided by the 'id_str' network block
 
61
option of \fBwpa_supplicant.conf\fR is exported to \fBwpa_action\fR as an 
 
62
environment variable, \fIWPA_ID_STR\fR. When 'id_str' is not configured for the
 
63
\fICURRENT\fR network block, 'default' is substituted for the absent
 
64
\fIWPA_ID_STR\fR environment variable.
 
65
.PP
 
66
A unique network identifier, \fIWPA_ID\fR, is exported to \fBwpa_action\fR. It
 
67
is the number assigned to the \fICURRENT\fR \fBwpa_supplicant\fR network block
 
68
(network_id).
 
69
.SH USAGE
 
70
The only reasons for \fBwpa_action\fR to be explicitly executed by the user is
 
71
to stop \fBwpa_cli\fR from controlling \fBifupdown\fR or reload the 
 
72
\fIwpa_supplicant.conf\fR file after editing.
 
73
.PP
 
74
.RS
 
75
\fBwpa_action\fR \fIeth1 stop\fR
 
76
.RE
 
77
.PP
 
78
Otherwise, \fBwpa_action\fR is given as an argument to a \fBwpa_cli\fR
 
79
daemon.
 
80
.PP
 
81
.RS
 
82
\fBwpa_cli\fR \fI-i eth1 -a /sbin/wpa_action -B\fR
 
83
.RE
 
84
.PP
 
85
This can be done by using the \fIwpa-roam\fR option in the \fBinterfaces\fR
 
86
file. \fIwpa-roam\fR takes one argument, a user provided 
 
87
\fBwpa_supplicant.conf\fR file. 
 
88
.PP
 
89
The inet \fIMETHOD\fR must be 'manual' for this interface, as it will
 
90
be configured according to \fBwpa_cli\fR action events. Also supply a 'default'
 
91
\fBinterfaces\fR stanza using the dhcp inet \fIMETHOD\fR so that networks
 
92
without an 'id_str' option can fallback to attempting to receive an ip via
 
93
dhcp. If one or more networks requires additional network configuration,
 
94
provide an unique 'id_str' for each network, and an \fBinterfaces\fR stanza
 
95
using the 'id_str' value as a \fILOGICAL\fR interface. The following interfaces
 
96
file is configured to use dhcp for any network without an 'id_str', a static ip
 
97
for the network with an 'id_str' of 'home_static' and dhcp plus an additional
 
98
post-up command for the network with an 'id_str' of 'uni'.
 
99
.PP
 
100
An example wpa_supplicant.conf configured to roam between 3 different networks:
 
101
.PP
 
102
.RS
 
103
.nf
 
104
network={
 
105
        ssid="foo"
 
106
        id_str="uni"
 
107
        key_mgmt=NONE
 
108
}
 
109
 
 
110
network={
 
111
        ssid="bar"
 
112
        id_str="home_static"
 
113
        psk=123456789...
 
114
}
 
115
 
 
116
network={
 
117
        ssid=""
 
118
        key_mgmt=NONE
 
119
}
 
120
.fi
 
121
.RE
 
122
.PP
 
123
The corresponding \fBinterfaces\fR file would contain \fILOGICAL\fR interfaces,
 
124
that correlate to each unique 'id_str' provided by the configuration file:
 
125
.PP
 
126
.RS
 
127
.nf
 
128
iface eth1 inet manual
 
129
        wpa-driver wext
 
130
        wpa-roam /path/to/wpa_supplicant.conf
 
131
 
 
132
iface default inet dhcp
 
133
 
 
134
iface uni inet dhcp
 
135
 
 
136
iface home_static inet static
 
137
        address 192.168.0.20
 
138
        netmask 255.255.255.0
 
139
        network 192.168.0.0
 
140
        broadcast 192.168.0.255
 
141
        gateway 192.168.0.1
 
142
.fi
 
143
.RE
 
144
.PP
 
145
.SH SEE ALSO
 
146
\fBwpa_cli(8)\fR, \fBwpa_supplicant(8)\fR, \fBwpa_supplicant.conf(5)\fR,
 
147
\fBifup(8)\fR, \fBinterfaces(5)\fR
 
148
.SH AUTHOR
 
149
This manual page was written by Kel Modderman <kelrin@tpg.com.au> for
 
150
the Debian GNU system (but may be used by others).