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