ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/gvpe/doc/gvpe.texi
(Generate patch)

Comparing gvpe/doc/gvpe.texi (file contents):
Revision 1.7 by root, Wed Mar 30 04:02:50 2016 UTC vs.
Revision 1.8 by root, Thu Nov 10 15:15:23 2016 UTC

… …
142 142
143 143
144@item 144@item
145EASY TO SETUP 145EASY TO SETUP
146 146
147A few lines of config (the config file is shared unmodified between all hosts) and a single run of @t{gvpectrl} to generate the keys suffices to make it work. 147A few lines of config (the config file is shared unmodified between all hosts) and generating an RSA key-pair on each node suffices to make it work.
148@refill 148@refill
149 149
150 150
151@item 151@item
152MAC-BASED SECURITY 152MAC-BASED SECURITY
… …
269@refill 269@refill
270By enabling routing on the gateway host that runs @t{gvpe} all nodes will be able to reach the other nodes. You can, of course, also use proxy ARP or other means of pseudo-bridging, or (best) full routing - the choice is yours. 270By enabling routing on the gateway host that runs @t{gvpe} all nodes will be able to reach the other nodes. You can, of course, also use proxy ARP or other means of pseudo-bridging, or (best) full routing - the choice is yours.
271@refill 271@refill
272 272
273 273
274@subsection STEP 2: create the RSA key pairs for all hosts 274@subsection STEP 2: create the RSA key pair for each node
275Run the following command to generate all key pairs for all nodes (that might take a while): 275Next you have to generate the RSA keys for the nodes. While you can set up GVPE so you can generate all keys on a single host and centrally distribute all keys, it is safer to generate the key for each node on the node, so that the secret/private key does not have to be copied over the network.
276@refill 276@refill
277To do so, run the following command to generate a key pair:
278@refill
277 279
278 280
279@example 281@example
280 gvpectrl -c /etc/gvpe -g 282 gvpectrl -c /etc/gvpe -g nodekey
283@end example
284
285This will create two files, @file{nodekey} and @file{nodekey.privkey}. The former should be copied to @file{/etc/gvpe/pubkey/@emph{nodename}} on the host where your config file is (you will have to create the @file{pubkey} directory first):
286@refill
287
288
281@end example 289@example
290 scp nodekey confighost:/etc/gvpe/pubkey/nodename
291@end example
282 292
283This command will put the public keys into @t{/etc/gvpe/pubkeys/@emph{nodename}} and the private keys into @t{/etc/gvpe/hostkeys/@emph{nodename}}. 293The private key @file{nodekey.privkey} should be moved to @file{/etc/gvpe/hostkey}:
284@refill 294@refill
295
296
297@example
298 mkdir -p /etc/gvpe
299 mv nodekey.privkey /etc/gvpe/hostkey
300@end example
301
285 302
286 303
287@subsection STEP 3: distribute the config files to all nodes 304@subsection STEP 3: distribute the config files to all nodes
288Now distribute the config files and private keys to the other nodes. This should be done in two steps, since only the private keys meant for a node should be distributed (so each node has only it's own private key). 305Now distribute the config files and public keys to the other nodes.
289@refill 306@refill
290The example uses rsync-over-ssh 307The example uses rsync-over-ssh to copy the config file and all the public keys:
291@refill 308@refill
292First all the config files without the hostkeys should be distributed:
293@refill
294 309
295 310
296@example 311@example
297 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkeys 312 rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkey
298 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkeys 313 rsync -avzessh /etc/gvpe 133.55.82.9:/etc/. --exclude hostkey
299 rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkeys 314 rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkey
300@end example
301
302Then the hostkeys should be copied:
303@refill
304
305
306@example
307 rsync -avzessh /etc/gvpe/hostkeys/first first.example.net:/etc/hostkey
308 rsync -avzessh /etc/gvpe/hostkeys/second 133.55.82.9:/etc/hostkey
309 rsync -avzessh /etc/gvpe/hostkeys/third third.example.net:/etc/hostkey
310@end example 315@end example
311 316
312You should now check the configuration by issuing the command @t{gvpectrl -c /etc/gvpe -s} on each node and verify it's output. 317You should now check the configuration by issuing the command @t{gvpectrl -c /etc/gvpe -s} on each node and verify it's output.
313@refill 318@refill
314 319
… …
335@end example 340@end example
336 341
337 342
338 343
339@subsection STEP 5: enjoy 344@subsection STEP 5: enjoy
340... and play around. Sending a -HUP (@t{gvpectrl -kHUP}) to the daemon will make it try to connect to all other nodes again. If you run it from inittab, as is recommended, @t{gvpectrl -k} (or simply @t{killall gvpe}) will kill the daemon, start it again, making it read it's configuration files again. 345... and play around. Sending a -HUP (@t{gvpectrl -kHUP}) to the daemon will make it try to connect to all other nodes again. If you run it from inittab @t{gvpectrl -k} (or simply @t{killall gvpe}) will kill the daemon, start it again, making it read it's configuration files again.
341@refill 346@refill
347To run the GVPE daemon permanently from your SysV init, you can add it to your @file{inittab}, e.g.:
348@refill
349
350
351@example
352 t1:2345:respawn:/bin/sh -c "exec nice -n-20 /path/to/gvpe -D node >/var/log/gvpe.log 2>&1"
353@end example
354
355For systems using systemd, you can use a unit file similar to this one:
356@refill
357
358
359@example
360 [Unit]
361 Description=gvpe
362 After=network.target
363 Before=remote-fs.target
364
365 [Service]
366 ExecStart=/path/to/gvpe -D node
367 KillMode=process
368 Restart=always
369
370 [Install]
371 WantedBy=multi-user.target
372@end example
373
342 374
343 375
344@section COPYRIGHTS AND LICENSES 376@section COPYRIGHTS AND LICENSES
345GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file COPYING that should be part of your distribution). 377GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file COPYING that should be part of your distribution).
346@refill 378@refill
… …
1149 1181
1150@item 1182@item
1151private-key = relative-path-to-key 1183private-key = relative-path-to-key
1152 1184
1153@cindex private-key 1185@cindex private-key
1154Sets the path (relative to the config directory) to the private key (default: @t{hostkey}). This is a printf format string so every @t{%} must be doubled. A single @t{%s} is replaced by the hostname, so you could use paths like @t{hostkeys/%s} to fetch the files at the location where @t{gvpectrl} puts them. 1186Sets the path (relative to the config directory) to the private key (default: @t{hostkey}). This is a printf format string so every @t{%} must be doubled. A single @t{%s} is replaced by the hostname, so you could use paths like @t{hostkeys/%s} to be able to share the same config directory between nodes.
1155@refill 1187@refill
1156Since only the private key file of the current node is used and the private key file should be kept secret per-node to avoid spoofing, it is not recommended to use this feature. 1188Since only the private key file of the current node is used and the private key file should be kept secret per-node to avoid spoofing, it is not recommended to use this feature this way though.
1157@refill 1189@refill
1158 1190
1159 1191
1160@item 1192@item
1161rekey = seconds 1193rekey = seconds
… …
1534Read configuration options from @emph{DIR}. 1566Read configuration options from @emph{DIR}.
1535@refill 1567@refill
1536 1568
1537 1569
1538@item 1570@item
1571@strong{-g}, @strong{--generate-key=path}
1572
1573Generates a single RSA key-pair. The public key will be stored in @file{@emph{path}} while the private key will be stored in @file{@emph{path} .privkey}. Neither file must be non-empty for this to succeed.
1574@refill
1575The public key file @file{@emph{path}} is normally copied to @file{pubkey/nodename} in the config directory on all nodes, while the private key @file{@emph{path}.privkey} should be copied to the file @file{hostkey} on the node the key is for.
1576@refill
1577It's recommended to generate the keypair on the node where it will be used, so that the private key file does not have to travel over the network.
1578@refill
1579
1580
1581@item
1539@strong{-g}, @strong{--generate-keys} 1582@strong{-G}, @strong{--generate-keys}
1540 1583
1541Generate public/private RSA key-pair and exit. 1584Generate public/private RSA key-pairs for all nodes not having a key and exit.
1585@refill
1586Note that in normal configurations this will fail, as there cna only be one private key per host. To make this configuration work you need to specify separate keyfiles for hostkeys in your config file, e.g.:
1587@refill
1588
1589
1590@example
1591 private-key = hostkeys/%s
1592@end example
1593
1594Such a configuration makes it easier to distribute a configuration centrally but requires private keys to be transported securely over the network.
1542@refill 1595@refill
1543 1596
1544 1597
1545@item 1598@item
1546@strong{-q}, @strong{--quiet} 1599@strong{-q}, @strong{--quiet}
… …
1742 1795
1743 1796
1744@item 1797@item
1745@t{/etc/gvpe/pubkey/*} 1798@t{/etc/gvpe/pubkey/*}
1746 1799
1747The directory containing the public keys for every node, usually autogenerated by executing @t{gvpectrl --generate-keys}. 1800The directory containing the public keys for every node, one file per node with the name of the node.
1801@refill
1802
1803
1804@item
1805@t{/etc/gvpe/hostkey}
1806
1807The file containing the private key of the node GVPE runs on. Unlike all the other files in the @file{/etc/gvpe} directory, this file usually differes for each node that GVPE runs on.
1748@refill 1808@refill
1749 1809
1750 1810
1751@item 1811@item
1752@t{/var/run/gvpe.pid} 1812@t{/var/run/gvpe.pid}

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines