Hackily fix indentation
[wiki.git] / doc / xvm / renumbering.mdwn
1 [[!meta title="XVM IP Address Renumbering Frequently Asked Questions"]]
2
3 This document aims to explain everything you should need to know about
4 XVM's IP renumbering.
5
6 [[!toc]]
7
8 ## What is this "renumbering" all about?  Didn't we already do this last year?
9
10 If you were an XVM user one year ago, you may remember having your VM(s)
11 renumbered from IP addresses beginning with `18.181` to IP addresses
12 beginning with `18.49` back then.  We are being required to renumber
13 again by IS&T.  Please contact IS&T if you have questions about why
14 we are being required to renumber.  The process this time will be very
15 similar, except that this time, addresses will be changing to ones beginning
16 with `18.25`.
17
18 ## Do I need to take any action?
19
20 That depends on your VM.  In many cases, you will not need to worry about
21 anything at all, and everything will be taken care of automatically.  Here
22 are the most common examples of reasons that you **will** need to take
23 special action and perhaps coordinate with us.  If any of the following
24 apply, please look through the rest of this FAQ to find out what you
25 should do:
26
27    * Your VM's network is statically configured (this is *not* the default; most VMs are configured with DHCP)
28    * You have an external (non-.mit.edu) DNS hostname configured to point to your VM's IP address
29    * Your VM runs an AFS client
30    * Your VM runs daemons that have your IP address hardcoded in their configurations
31
32 ## I've already handled a server that had to be migrated in my dorm/office.  Will XVM's migrations work the same way?
33
34 No.  We have done a great deal of work to attempt to make VM migrations as
35 smooth as possible; please keep reading to learn what to expect.
36
37 ## If my VM does not require special coordination, how will my automatic IP migration work?
38
39 Once we set your VM to be migrated, the next time it renews its DHCP lease
40 (which should happen within an hour), your VM will be given its new IP
41 address.  At the same time that this happens, the XVM infrastructure will
42 set up a temporary NAT to accept traffic at your VM's old IP address and
43 forward it to the new address.  This means that, regardless of whether
44 users try to contact your VM at its old address or its new address, they will
45 successfully reach it.  There will be no period where your VM will be
46 unreachable.
47
48 At the same time as your VM receives its new IP address, the XVM DNS server,
49 which answers lookups for the hostname `$VMNAME.xvm.mit.edu`, will be
50 updated (previous lookups will only be cached for at most 15 minutes).
51 Sometime during the following day, we will update the record for your
52 VM's IP address in MIT's Moira database, which controls lookups for
53 any custom `.mit.edu` hostname you may have requested (these default
54 to names like `xvm-number-xyz.mit.edu` if you have not requested a
55 custom hostname).
56
57 Some time after all cached lookups of the `.mit.edu` hostnames have expired,
58 we will remove the temporary NAT, and your VM's IP migration will be
59 complete.
60
61 ## If I have active connections when my IP address is migrated, will they continue to work?
62
63 No, unfortunately, there are limits to what we can do to maintain your VM's
64 connectivity.  If you have active connections (for example, ssh) when your
65 IP address is migrated, those connections will be broken.  However, you
66 will be able to immediately reestablish those connections at either the
67 new or old IP address.
68
69 If you are running something like a webserver, however, and you have users
70 interacting with your site, they will be able to continue clicking around
71 your website as your VM migrates IP addresses.
72
73 ## When will my IP addresses change?  Can I postpone this?  Can I migrate early?
74
75 We plan to begin automated migrations of VMs to their new IP addresses on
76 Monday, August 5, 2019.  This process is expected to take somewhere between
77 a few days and one week.
78
79 There are several forces at play that we do not control, so there is very
80 limited flexibility that we can offer.
81
82 If your VM requires special coordination in order to be migrated, we will
83 work with you to find a time that works well, possibly earlier than the
84 automated migrations.  You should see other questions in this FAQ to determine
85 if your VM will require special handling, and get in touch with us if so
86 by sending e-mail to <xvm@mit.edu>.  If you would like your VM to be
87 migrated early, perhaps because you will be away during the week we plan
88 to perform most automated migrations and you would like to be available to
89 ensure that all has gone well once your machine has migrated, we will be
90 happy to migrate your machine early - once again, please contact us at
91 <xvm@mit.edu> and be sure to tell us the name of the VM and when you will
92 be ready for it to be migrated.
93
94 ## What will my new IP address be?  How can I tell if my migration has happened?
95
96 Your old IP address was of the form `18.49.xxx.yyy`.  Your new IP address
97 will be of the form `18.25.zzz.yyy` where `yyy` will remain the same and
98 `zzz` will be `xxx + 128`.  If your VM's networking is statically configured
99 and you will be updating this info manually because you cannot switch to
100 using DHCP, it is critical that you note that the gateway will
101 also be changing.  Please see the question on what to do if you use static
102 addressing below.
103
104 Before your migration, you can see what your new network parameters will
105 be by visiting XVM's website at <https://xvm.mit.edu/> and clicking the
106 link for your VM to go to its info page.  On that page, look for a line that
107 begins with "Other Address:".
108
109 Once your migration has occurred, the "IP:" line on the info page and
110 the IP address on the line for your VM on XVM's main webpage will show
111 your new address, which begins with `18.25`.
112
113 ## My VM's networking is statically configured.  What should I do?
114
115 The simplest and best way to handle this is to reconfigure your VM to
116 use DHCP, if at all possible, as soon as you can.  If you can change your
117 VM to use DHCP, then you needn't do anything else, and you don't need to
118 contact us to let us know that you've done so - everything will just
119 proceed automatically.
120
121 If there is a reason that you cannot reconfigure your VM to use DHCP,
122 then once we have begun migrating VM IPs, you should visit our website
123 at <https://xvm.mit.edu/> and click the link for your VM to go to its
124 info page.  On that page, you will be able to see both the current and
125 new IP address, netmask, and gateway.  There will also be a new button
126 on the page with a message above it saying that you can reconfigure your VM 
127 with the new IP parameters (make sure you get the gateway
128 correct; it will not be the same as the old one) and then click the
129 button.  If your VM is running, clicking the button will powercycle your
130 VM.  If your VM is not running, clicking the button will update XVM's
131 configuration for your VM and tell you to turn it on to complete the
132 transition.  You need to edit the configuration files for your VM's
133 networking on the VM **before** you click the button.
134
135 If the above works fine for you, you do not need to contact us.
136
137 ## I have an external (non-.mit.edu) DNS hostname pointed at my VM.  What should I do?
138
139 You should contact us at <xvm@mit.edu> to coordinate.  Once your VM's
140 IP address has been migrated, we will delay removing the NAT that allows
141 both the old and new addresses to work until you have updated your external
142 DNS.  You should **not** update your external DNS before your machine's
143 IP address has been migrated, because the new address will not work before
144 that point.
145
146 ## My VM runs an AFS client.  What should I do?
147
148 You should wait for your VM's IP address to be migrated.  Once that
149 happens, you will need to either restart your AFS client, or (perhaps
150 more easily in some cases) reboot your VM.  If you are curious about the
151 technical reasons for this, see the next paragraph.  You do not need to
152 contact us about this.
153
154 Restarting the AFS client after you are renumbered is necessary because
155 after your AFS client starts up, the first time it talks to each of
156 the fileservers in the AFS cells you use, it registers a list of the
157 IP addresses it has with those fileservers.  That list will not be
158 updated when your VM's IP address changes (there is a command
159 `fs setclientaddrs` to change the list of IP addresses that will be
160 sent to fileservers your client has not yet communicated with, but
161 it will not update the addresses on file with servers your VM *has*
162 already communicated with).  This will make the fileservers unable
163 to inform your VM when changes have been made to files once the
164 temporary NAT is removed, and you will begin to experience mysterious
165 problems with AFS.
166
167 ## My VM runs daemons that have my IP address hardcoded in their configuration files.  What should I do?
168
169 If at all possible, you should reconfigure them not to have IP addresses
170 hardcoded.  If you're able to do that, you won't need to get in touch with
171 us.
172
173 If any of your daemons cannot work without a hardcoded IP address, you will
174 need to get in touch with us at <xvm@mit.edu> to coordinate a time to
175 migrate your VM's IP address.  Even though we will continue to send traffic
176 for the old IP address to your VM for a period of time after its migration,
177 we will do this with a NAT (essentially, we will take packets destined for
178 your VM's old IP address, and we will change the destination address on them
179 to the new address); your VM will only have an interface set up for the
180 new address, and any daemons that try to make use of the old address in
181 their configurations will encounter errors.
182
183 We will work out a time with you when your IP address can be migrated.
184 At that time, we will set your VM to migrate, and you will change the
185 configuration files for your daemons.  Once the machine's IP address
186 migrates, you will restart the daemons or reboot your server.
187
188 ## Should I contact you about my VM's renumbering?  When do I need to contact you by?
189
190 If you have questions that are not answered by this FAQ, you should
191 contact us and we'll do our best to answer them.  If your VM requires
192 special coordination (for example, due to any of the reasons listed in
193 the "Do I need to take any action?" question near the top of this page),
194 you should definitely contact us no later than Sunday, August 4.  If anything
195 goes wrong during your VM's migration, again, we need to hear from you.
196 Finally, if you have feedback about the process that you would like to share,
197 we welcome you to contact us.
198
199 If none of the above applies to you, we hope that your migration experience
200 is very smooth, and there is no need for you to get in touch with us.  Please
201 keep in mind that, while we will do our best to answer messages that we
202 receive, there are approximately 1,200 VMs that we need to get migrated in
203 a very short time, and our resources are limited, so there is no need to
204 contact us just to acknowledge receipt of the announcement or to report that
205 your VM's migration was successful.
206
207