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 | ||
35744ac3 MW |
120 | Usually, if a property has already been defined on an item, then |
121 | it is an error to try to redefine it. But some properties are | |
122 | list-like: the values are accumulated into a single list. | |
6b27510e MW |
123 | |
124 | Mostly, properties are written to corresponding assignments in | |
125 | the generated Secnet configuration file, . The entries below | |
126 | describe how properties are translated into assignments. | |
127 | ||
128 | contact EMAIL | |
129 | Becomes a `Contact address' comment in the output. | |
130 | Acceptable at all levels; required separately at VPN and | |
131 | location levels. | |
132 | ||
133 | dh P G | |
a4902c66 MW |
134 | dh GROUP-NAME |
135 | Assigns a Diffie--Hellman closure to the `dh' key. If | |
136 | MODULUS and GENERATOR are given, the closure is | |
137 | constructed as `diffie-hellman(P, G)'. If a GROUP-NAME | |
138 | is given, it must be one of `x25519' or `x448', and the | |
139 | like-named pre-existing DH closure is used. This is a | |
140 | listish property: it can be set more than once and the | |
141 | values are accumulated into a list in the output. | |
142 | ||
143 | Acceptable at all levels; required at site level. | |
6b27510e MW |
144 | |
145 | hash HASH-NAME | |
146 | Assigns the HASH-NAME to the `hash' key. The HASH-NAME | |
757aecff MW |
147 | must be one of `md5', `sha1', or `sha512', and the |
148 | corresponding hash closure is used. Acceptable at all | |
149 | levels; required at site level. | |
6b27510e MW |
150 | |
151 | key-lifetime INT | |
152 | setup-timeout INT | |
153 | setup-retries INT | |
154 | wait-time INT | |
155 | renegotiate-time INT | |
156 | Assign integers to the like-named key. Acceptable at | |
157 | all levels. | |
158 | ||
159 | restrict-nets NETWORK NETWORK ... | |
160 | This item and its descendents may only define `networks' | |
161 | and `peer' properties with addresses within the listed | |
162 | NETWORKs, each of which has the form IPADDR/MASK, where | |
163 | the IPADDR is an IPv4 address in dotted-quad form, and | |
164 | the MASK is either a netmask in dotted-quad form or a | |
165 | prefix length. Becomes a comment n the output. | |
166 | Acceptable at all levels. | |
167 | ||
168 | networks NETWORK NETWORK ... | |
169 | Assigns a list of NETWORKs to the `routes' key in a | |
170 | netlink application (see below). See `restrict-nets' | |
171 | for the syntax of a NETWORK. Acceptable only at site | |
172 | level; required at site level. | |
173 | ||
174 | address HOSTNAME PORT | |
175 | Assigns HOSTNAME to the `address' key and PORT (an | |
176 | integer) to the `port' key. Acceptable only at site | |
177 | level. May be omitted for mobile sites. | |
178 | ||
179 | peer IPADDR | |
180 | Assigns IPADDR to the `ptp-address' key in a netlink | |
181 | application (see below). IPADDR must be an IPv4 address | |
182 | in dotted-quad form. Acceptable only at site level; | |
183 | required at site level. | |
184 | ||
185 | pubkey HUNOZ E N | |
186 | Assigns a public-key closure to the `key' key, | |
187 | constructed as `rsa-public(E, N)'. The argument HUNOZ | |
188 | must be an integer, but is otherwise ignored; it's | |
189 | conventionally the length of N in bits. Acceptable only | |
190 | at site level; required at site level. | |
191 | ||
192 | mobile BOOL | |
193 | Assigns BOOL to the `mobile' key. Acceptable only at | |
194 | site level, but optional. | |
195 | ||
196 | ||
197 | OUTPUT STRUCTURE | |
198 | ||
199 | The program produces a Secnet configuration fragment with the | |
200 | structure described below, suitable for inclusion using the | |
201 | `include' keyword. | |
202 | ||
203 | PREFIXvpn-data { | |
204 | VPN { | |
205 | # Contact email address: EMAIL | |
206 | [ # restrict-nets: NETWORKS ] | |
207 | [ VPN-PROPERTIES ] | |
208 | LOCATION { | |
209 | # Contact email address: EMAIL | |
210 | [ # restrict-nets: NETWORKS ] | |
211 | [ LOCATION-PROPERTIES ] | |
212 | SITE { | |
213 | [ # Contact email address: EMAIL ] | |
214 | [ # restrict-nets: NETWORKS ] | |
215 | name "VPN/LOCATION/NAME"; | |
216 | SITE-PROPERTIES | |
217 | link netlink { | |
218 | routes NETWORK ...; | |
219 | ptp-address IPADDR; | |
220 | }; | |
221 | }; | |
222 | [ MORE SITES ... ] | |
223 | }; | |
224 | [ MORE LOCATIONS ... ] | |
225 | }; | |
226 | [ MORE VPNS ... ] | |
227 | }; | |
228 | ||
229 | PREFIXvpn { | |
230 | VPN { | |
231 | LOCATION PREFIXvpn-data/VPN/LOCATION/SITE, ...; | |
232 | [ MORE LOCATIONS ] | |
233 | all-sites LOCATION, ...; | |
234 | }; | |
235 | }; | |
236 | ||
237 | PREFIXall-sites PREFIXvpn/VPN/all-sites, ...; | |
238 | ||
239 | Note in particular the implicit dependency on a pure closure | |
240 | named `netlink' used to set the `link' key in each site | |
241 | definition. Usually, this will be constructed by a partial | |
242 | application of the built-in `userv-ipif' or `tun' closures. |