Commit | Line | Data |
---|---|---|
6b27510e MW |
1 | USAGE |
2 | ||
3 | make-secnet-sites [-P PREFIX] [IN [OUT]] | |
4 | make-secnet-sites -u HEADER GRPDIR SITESFILE GROUP | |
5 | ||
6 | The `-P' option sets the PREFIX string, mentioned below in | |
7 | `OUTPUT STRUCTURE'; the default is empty. | |
8 | ||
9 | In the former mode, `make-secnet-sites' reads a single input | |
10 | file from IN (defaulting to standard input), and writes a Secnet | |
11 | configuration fragment to OUT (defaulting to standard output). | |
12 | ||
13 | In the latter, `make-secnet-sites' expects to have been invoked | |
14 | via GNU Userv. It verifies that GROUP is listed in the | |
15 | `USERV_GROUP' environment variable. It then processes the | |
16 | HEADER input, which should say `end-defintions' somewhere, to | |
17 | enable restrictions, and then user input on standard input. If | |
18 | the combination of the two is acceptable, it writes a copy of | |
19 | the user input to the file `GRPDIR/RGROUP' (the `R' is literal) | |
20 | preceded by a comment logging the time and the value of the | |
21 | `USERV_USER' environment variable, and writes a file named | |
22 | SITESFILE consisting of the concatenation of: | |
23 | ||
24 | * a header comment logging the time and the value of the | |
25 | `USERV_USER' environment variable, and a reminder that this | |
26 | is `make-secnet-sites' input; | |
27 | ||
28 | * the HEADER, with any `include' lines replaced by the files | |
29 | they include; and | |
30 | ||
31 | * each of the `GRPDIR/R*' files, in some arbitrary order. | |
32 | ||
33 | This SITESFILE can later be processed in the former mode to | |
34 | produce Secnet configuration. | |
35 | ||
36 | ||
37 | INPUT SYNTAX | |
38 | ||
39 | The input files have a simple line-based syntax. Blank lines, | |
40 | and lines beginning with a `#' character, are ignored. Other | |
41 | lines consist of a keyword followed by arguments, and separated | |
42 | by horizontal whitespace. There is no quoting, and it is not | |
43 | possible to include horizontal whitespace in an argument. | |
44 | ||
45 | An input file describes a number of virtual private networks | |
46 | (`VPNs'). Each VPN consists of a number of locations, and each | |
47 | location consists of a number of sites, thus forming (together | |
48 | with the root) a fixed four-level hierarchy. The root, VPNs, | |
49 | locations, and sites can each have a number of properties | |
50 | attached to them: each level in the hierarchy has a different | |
51 | set of permissable properties. | |
52 | ||
53 | Most keywords define properties on a `current' item in the | |
54 | hierarchy. Some change which item is current, possibly creating | |
55 | a new item. A few are special. | |
56 | ||
57 | First, the navigation keywords. | |
58 | ||
59 | vpn NAME | |
60 | Switch to the VPN called NAME, which is a direct child | |
61 | of the root, creating it if necessary. Subsequent | |
62 | properties, up until the next navigation keyword, are | |
63 | attached directly to the VPN. | |
64 | ||
65 | A VPN item becomes a dictionary named `NAME' within the | |
66 | `PREFIXvpn-data' dictionary in the generated output. | |
67 | ||
68 | location NAME [GROUP] | |
69 | Switch to the location called NAME, which is a direct | |
70 | child of the most recently mentioned VPN, creating it if | |
71 | necessary. The GROUP name may be omitted (and is anyway | |
72 | ignored) if the location already exists. It is an error | |
73 | if there is no current VPN. Subsequent properties, up | |
74 | until the next navigation keyword, are attached directly | |
75 | to the location. | |
76 | ||
77 | A location item becomes a dictionary named `NAME' within | |
78 | its parent VPN's dictionary in the generated output. | |
79 | ||
80 | site NAME | |
81 | Switch to the site called NAME, which is a direct | |
82 | child of the most recently mentioned location, creating | |
83 | it if necessary. It is an error if there is no current | |
84 | location. Subsequent properties, up until the next | |
85 | navigation keyword, are attached directly to the site. | |
86 | ||
87 | A location item becomes a dictionary named `NAME' within | |
88 | its parent location's dictionary in the generated | |
89 | output. | |
90 | ||
91 | Now, the special keywords. | |
92 | ||
93 | include FILE | |
94 | Read lines from FILE, as if they'd appeared at this | |
95 | point in the input. If the FILE name is relative, it is | |
96 | interpreted relative to the directory containing the | |
97 | most recently opened file. (This seems to be a bug.) | |
98 | ||
99 | The `include' keyword is only permitted before the | |
100 | `end-defintions' marker in a HEADER file processed using | |
101 | the `-u' option. | |
102 | ||
103 | end-definitions | |
104 | After this keyword, the following restrictions apply. | |
105 | ||
106 | * The `include' keyword can no longer be used. | |
107 | ||
108 | * It is not permitted to define new VPNs and | |
109 | locations. | |
110 | ||
111 | * It is not permitted to append new items to root, | |
112 | VPN, and location properties which are already | |
113 | defined. (Assigning new properties is permitted.) | |
114 | ||
8644ac83 MW |
115 | * It is not permitted to define new VPN-level |
116 | properties. | |
117 | ||
6b27510e MW |
118 | Finally, the properties. |
119 | ||
120 | If a property has already been defined on an item, then it is an | |
121 | error to try to redefine it. | |
122 | ||
123 | Mostly, properties are written to corresponding assignments in | |
124 | the generated Secnet configuration file, . The entries below | |
125 | describe how properties are translated into assignments. | |
126 | ||
127 | contact EMAIL | |
128 | Becomes a `Contact address' comment in the output. | |
129 | Acceptable at all levels; required separately at VPN and | |
130 | location levels. | |
131 | ||
132 | dh P G | |
133 | Assigns a Diffie--Hellman closure to the `dh' key, | |
134 | constructed as `diffie-hellman(P, G)'. Acceptable at all | |
135 | levels; required at site level. | |
136 | ||
137 | hash HASH-NAME | |
138 | Assigns the HASH-NAME to the `hash' key. The HASH-NAME | |
139 | must be one of `md5' or `sha1', and the corresponding | |
140 | hash closure is used. Acceptable at all levels; | |
141 | required at site level. | |
142 | ||
143 | key-lifetime INT | |
144 | setup-timeout INT | |
145 | setup-retries INT | |
146 | wait-time INT | |
147 | renegotiate-time INT | |
148 | Assign integers to the like-named key. Acceptable at | |
149 | all levels. | |
150 | ||
151 | restrict-nets NETWORK NETWORK ... | |
152 | This item and its descendents may only define `networks' | |
153 | and `peer' properties with addresses within the listed | |
154 | NETWORKs, each of which has the form IPADDR/MASK, where | |
155 | the IPADDR is an IPv4 address in dotted-quad form, and | |
156 | the MASK is either a netmask in dotted-quad form or a | |
157 | prefix length. Becomes a comment n the output. | |
158 | Acceptable at all levels. | |
159 | ||
160 | networks NETWORK NETWORK ... | |
161 | Assigns a list of NETWORKs to the `routes' key in a | |
162 | netlink application (see below). See `restrict-nets' | |
163 | for the syntax of a NETWORK. Acceptable only at site | |
164 | level; required at site level. | |
165 | ||
166 | address HOSTNAME PORT | |
167 | Assigns HOSTNAME to the `address' key and PORT (an | |
168 | integer) to the `port' key. Acceptable only at site | |
169 | level. May be omitted for mobile sites. | |
170 | ||
171 | peer IPADDR | |
172 | Assigns IPADDR to the `ptp-address' key in a netlink | |
173 | application (see below). IPADDR must be an IPv4 address | |
174 | in dotted-quad form. Acceptable only at site level; | |
175 | required at site level. | |
176 | ||
177 | pubkey HUNOZ E N | |
178 | Assigns a public-key closure to the `key' key, | |
179 | constructed as `rsa-public(E, N)'. The argument HUNOZ | |
180 | must be an integer, but is otherwise ignored; it's | |
181 | conventionally the length of N in bits. Acceptable only | |
182 | at site level; required at site level. | |
183 | ||
184 | mobile BOOL | |
185 | Assigns BOOL to the `mobile' key. Acceptable only at | |
186 | site level, but optional. | |
187 | ||
188 | ||
189 | OUTPUT STRUCTURE | |
190 | ||
191 | The program produces a Secnet configuration fragment with the | |
192 | structure described below, suitable for inclusion using the | |
193 | `include' keyword. | |
194 | ||
195 | PREFIXvpn-data { | |
196 | VPN { | |
197 | # Contact email address: EMAIL | |
198 | [ # restrict-nets: NETWORKS ] | |
199 | [ VPN-PROPERTIES ] | |
200 | LOCATION { | |
201 | # Contact email address: EMAIL | |
202 | [ # restrict-nets: NETWORKS ] | |
203 | [ LOCATION-PROPERTIES ] | |
204 | SITE { | |
205 | [ # Contact email address: EMAIL ] | |
206 | [ # restrict-nets: NETWORKS ] | |
207 | name "VPN/LOCATION/NAME"; | |
208 | SITE-PROPERTIES | |
209 | link netlink { | |
210 | routes NETWORK ...; | |
211 | ptp-address IPADDR; | |
212 | }; | |
213 | }; | |
214 | [ MORE SITES ... ] | |
215 | }; | |
216 | [ MORE LOCATIONS ... ] | |
217 | }; | |
218 | [ MORE VPNS ... ] | |
219 | }; | |
220 | ||
221 | PREFIXvpn { | |
222 | VPN { | |
223 | LOCATION PREFIXvpn-data/VPN/LOCATION/SITE, ...; | |
224 | [ MORE LOCATIONS ] | |
225 | all-sites LOCATION, ...; | |
226 | }; | |
227 | }; | |
228 | ||
229 | PREFIXall-sites PREFIXvpn/VPN/all-sites, ...; | |
230 | ||
231 | Note in particular the implicit dependency on a pure closure | |
232 | named `netlink' used to set the `link' key in each site | |
233 | definition. Usually, this will be constructed by a partial | |
234 | application of the built-in `userv-ipif' or `tun' closures. |