Cluster-keys-replacement: update documentation
[ganeti-github.git] / doc / cluster-keys-replacement.rst
1 ========================
2 Cluster Keys Replacement
3 ========================
4
5 Ganeti uses both SSL and SSH keys, and actively modifies the SSH keys
6 on the nodes.  As result, in order to replace these keys, a few extra
7 steps need to be followed.
8
9 For an example when this could be needed, see the thread at
10 `Regenerating SSL and SSH keys after the security bug in Debian's
11 OpenSSL
12 <http://groups.google.com/group/ganeti/browse_thread/thread/30cc95102dc2123e>`_.
13
14 Ganeti uses OpenSSL for encryption on the RPC layer and SSH for
15 executing commands. The SSL certificate is automatically generated
16 when the cluster is initialized and it's copied to added nodes
17 automatically together with the master's SSH host key.
18
19 Note that paths below may vary depending on your distribution. In
20 general, modifications should be done on the master node and then
21 distributed to all nodes of a cluster (possibly using a pendrive - but
22 don't forget to use "shred" to remove files securely afterwards).
23
24 Replacing SSL keys
25 ==================
26
27 The cluster-wide SSL key is stored in ``/var/lib/ganeti/server.pem``.
28 Besides that, since Ganeti 2.11, each node has an individual node
29 SSL key, which is stored in ``/var/lib/ganeti/client.pem``. This
30 client certificate is signed by the cluster-wide SSL certficate.
31
32 To renew the individual node certificates, run this command::
33
34   gnt-cluster renew-crypto --new-node-certificates
35
36 Run the following command to generate a new cluster-wide certificate::
37
38   gnt-cluster renew-crypto --new-cluster-certificate
39
40 Note that this triggers both, the renewal of the cluster certificate
41 as well as the renewal of the individual node certificate. The reason
42 for this is that the node certificates are signed by the cluster
43 certificate and thus they need to be renewed and signed as soon as
44 the changes certificate changes. Therefore, the command above is
45 equivalent to::
46
47   gnt-cluster renew-crypto --new-cluster-certificate --new-node-certificates
48
49 On older versions, which don't have this command, use this instead::
50
51   chmod 0600 /var/lib/ganeti/server.pem &&
52   openssl req -new -newkey rsa:1024 -days 1825 -nodes \
53    -x509 -keyout /var/lib/ganeti/server.pem \
54    -out /var/lib/ganeti/server.pem -batch &&
55   chmod 0400 /var/lib/ganeti/server.pem &&
56   /etc/init.d/ganeti restart
57
58   gnt-cluster copyfile /var/lib/ganeti/server.pem
59
60   gnt-cluster command /etc/init.d/ganeti restart
61
62 Note that older versions don't have individual node certificates and thus
63 one does not have to handle the creation and distribution of them.
64
65
66 Replacing SSH keys
67 ==================
68
69 There are two sets of SSH keys in the cluster: the host keys (both DSA
70 and RSA, though Ganeti only uses the RSA one) and the root's DSA key
71 (Ganeti uses DSA for historically reasons, in the future RSA will be
72 used).
73
74 host keys
75 +++++++++
76
77 These are the files named ``/etc/ssh/ssh_host_*``. You need to
78 manually recreate them; it's possibly that the startup script of
79 OpenSSH will generate them if they don't exist, or that the package
80 system regenerates them.
81
82 Also make sure to copy the master's SSH host keys to all other nodes.
83
84 cluster public key file
85 +++++++++++++++++++++++
86
87 The new public rsa host key created in the previous step must be added
88 in two places:
89
90 #. known hosts file, ``/var/lib/ganeti/known_hosts``
91 #. cluster configuration file, ``/var/lib/ganeti/config.data``
92
93 Edit these two files and update them with newly generated SSH host key
94 (in the previous step, take it from the
95 ``/etc/ssh/ssh_host_rsa_key.pub``).
96
97 For the ``config.data`` file, please look for an entry named
98 ``rsahostkeypub`` and replace the value for it with the contents of
99 the ``.pub`` file. For the ``known_hosts`` file, you need to replace
100 the old key with the new one on each line (for each host).
101
102 root's key
103 ++++++++++
104
105 These are the files named ``~root/.ssh/id_dsa*``.
106
107 Run this command to rebuild them::
108
109   ssh-keygen -t dsa -f ~root/.ssh/id_dsa -q -N ""
110
111 root's ``authorized_keys``
112 ++++++++++++++++++++++++++
113
114 This is the file named ``~root/.ssh/authorized_keys``.
115
116 Edit file and update it with the newly generated root key, from the
117 ``id_dsa.pub`` file generated in the previous step.
118
119 Finish
120 ======
121
122 In the end, the files mentioned above should be identical for all
123 nodes in a cluster. Also do not forget to run ``gnt-cluster verify``.