Add XVM renumbering FAQ
[wiki.git] / doc / xvm / renumbering.mdwn
diff --git a/doc/xvm/renumbering.mdwn b/doc/xvm/renumbering.mdwn
new file mode 100644 (file)
index 0000000..5ec565d
--- /dev/null
@@ -0,0 +1,233 @@
+[[!meta title="XVM IP Address Renumbering Frequently Asked Questions"]]
+
+This document aims to explain everything you should need to know about
+XVM's IP renumbering.
+
+[[!toc]]
+
+## What is this "renumbering" all about?
+
+As you may have heard, MIT has recently sold half of its IPv4 address space
+to Amazon in order to fund various network infrastructure upgrade projects.
+While there are enough remaining addresses for everyone and everything that
+was using one before, some rearrangement is required to make sure that
+everyone's IP addresses are in the smaller space that will be left after
+Amazon takes over the space that they have purchased.  That takeover will
+happen later in June.
+
+All of the IP addresses used by VMs on XVM since its inception were,
+unfortunately, in the part of MIT's IP address space that has been sold to
+Amazon, and thus all of our IP addresses need to change.  You can read the
+official explanation of this sale and MIT's upcoming network upgrades
+[here](https://ist.mit.edu/network/next-gen-mitnet-faq), but be sure to
+continue reading this FAQ, because IS&T's description of how the academic
+buildings and residence halls are being migrated does not apply to XVM.
+
+## Do I need to take any action?
+
+That depends on your VM.  In many cases, you will not need to worry about
+anything at all, and everything will be taken care of automatically.  Here
+are the most common examples of reasons that you **will** need to take
+special action and perhaps coordinate with us.  If any of the following
+apply, please look through the rest of this FAQ to find out what you
+should do:
+
+   * Your VM's network is statically configured (this is *not* the default; most VMs are configured with DHCP)
+   * You have an external (non-.mit.edu) DNS hostname configured to point to your VM's IP address
+   * Your VM runs an AFS client
+   * Your VM runs daemons that have your IP address hardcoded in their configurations
+
+## I've already handled a server that had to be migrated in my dorm/office.  Will XVM's migrations work the same way?
+
+No.  We have done a great deal of work to attempt to make VM migrations as
+smooth as possible; please keep reading to learn what to expect.
+
+## If my VM does not require special coordination, how will my automatic IP migration work?
+
+Once we set your VM to be migrated, the next time it renews its DHCP lease
+(which should happen within an hour), your VM will be given its new IP
+address.  At the same time that this happens, the XVM infrastructure will
+set up a temporary NAT to accept traffic at your VM's old IP address and
+forward it to the new address.  This means that, regardless of whether
+users try to contact your VM at its old address or its new address, they will
+successfully reach it.  There will be no period where your VM will be
+unreachable.
+
+At the same time as your VM receives its new IP address, the XVM DNS server,
+which answers lookups for the hostname `$VMNAME.xvm.mit.edu`, will be
+updated (previous lookups will only be cached for at most 15 minutes).
+Sometime during the following day, we will update the record for your
+VM's IP address in MIT's Moira database, which controls lookups for
+any custom `.mit.edu` hostname you may have requested (these default
+to names like `xvm-number-xyz.mit.edu` if you have not requested a
+custom hostname).
+
+Some time after all cached lookups of the `.mit.edu` hostnames have expired,
+we will remove the temporary NAT, and your VM's IP migration will be
+complete.
+
+## If I have active connections when my IP address is migrated, will they continue to work?
+
+No, unfortunately, there are limits to what we can do to maintain your VM's
+connectivity.  If you have active connections (for example, ssh) when your
+IP address is migrated, those connections will be broken.  However, you
+will be able to immediately reestablish those connections at either the
+new or old IP address.
+
+If you are running something like a webserver, however, and you have users
+interacting with your site, they will be able to continue clicking around
+your website as your VM migrates IP addresses.
+
+## When will my IP addresses change?  Can I postpone this?  Can I migrate early?
+
+We plan to begin automated migrations of VMs to their new IP addresses on
+Monday, June 4, 2018.  This process is expected to take somewhere between
+a few days and one week.
+
+There are several forces at play that we do not control, so there is very
+limited flexibility that we can offer.  Amazon will take control of the
+space that they have purchased on June 26, 2018.  IS&T needs SIPB and XVM to
+vacate our old IP space well before then so that they can carry out various
+preparatory tasks before the official transfer to Amazon.
+
+If your VM requires special coordination in order to be migrated, we will
+work with you to find a time that works well, possibly earlier than the
+automated migrations.  You should see other questions in this FAQ to determine
+if your VM will require special handling, and get in touch with us if so
+by sending e-mail to <xvm@mit.edu>.  If you would like your VM to be
+migrated early, perhaps because you will be away during the week we plan
+to perform most automated migrations and you would like to be available to
+ensure that all has gone well once your machine has migrated, we will be
+happy to migrate your machine early - once again, please contact us at
+<xvm@mit.edu> and be sure to tell us the name of the VM and when you will
+be ready for it to be migrated.
+
+## What will my new IP address be?  How can I tell if my migration has happened?
+
+Your old IP address was of the form `18.181.xxx.yyy`.  Your new IP address
+will be of the form `18.49.xxx.yyy` where `xxx` and `yyy` will remain the
+same.  If your VM's networking is statically configured and you will be
+updating this info manually because you cannot switch to using DHCP, it
+is critical that you note that the gateway and netmask will also be changing.
+Please see the question on what to do if you use static addressing below.
+
+Before your migration, you can see what your new network parameters will
+be by visiting XVM's website at <https://xvm.mit.edu/> and clicking the
+link for your VM to go to its info page.  On that page, look for a line that
+begins with "Other Address:".
+
+Once your migration has occurred, the "IP:" line on the info page and
+the IP address on the line for your VM on XVM's main webpage will show
+your new address, which begins with `18.49`.
+
+## I rebooted my VM after its IP migration happened, and now I can't reach it on the network.  What should I do?
+
+The very first time you restart your VM after its IP migration has occurred,
+it is necessary to do so by completely turning it off and then turning it
+back on.  A reboot is not sufficient due to some internal state on the
+XVM infrastructure servers that is not cleared out when a VM reboots without
+being turned completely off.  Once the VM has been through one complete
+powercycle, further reboots should work fine.  We apologize for the
+inconvenience.
+
+## My VM's networking is statically configured.  What should I do?
+
+The simplest and best way to handle this is to reconfigure your VM to
+use DHCP, if at all possible, as soon as you can.  If you can change your
+VM to use DHCP, then you needn't do anything else, and you don't need to
+contact us to let us know that you've done so - everything will just
+proceed automatically.
+
+If there is a reason that you cannot reconfigure your VM to use DHCP,
+then once we have begun migrating VM IPs, you should visit our website
+at <https://xvm.mit.edu/> and click the link for your VM to go to its
+info page.  On that page, you will be able to see both the current and
+new IP address, netmask, and gateway.  There will also be a new button
+on the page with a message above it saying that you can reconfigure your VM 
+with the new IP parameters (make sure you get the netmask and gateway
+correct; they will not be the same as the old ones) and then click the
+button.  If your VM is running, clicking the button will powercycle your
+VM.  If your VM is not running, clicking the button will update XVM's
+configuration for your VM and tell you to turn it on to complete the
+transition.  You need to edit the configuration files for your VM's
+networking on the VM **before** you click the button.
+
+If the above works fine for you, you do not need to contact us.
+
+## I have an external (non-.mit.edu) DNS hostname pointed at my VM.  What should I do?
+
+You should contact us at <xvm@mit.edu> to coordinate.  Once your VM's
+IP address has been migrated, we will delay removing the NAT that allows
+both the old and new addresses to work until you have updated your external
+DNS.  You should **not** update your external DNS before your machine's
+IP address has been migrated, because the new address will not work before
+that point.
+
+## My VM runs an AFS client.  What should I do?
+
+You should wait for your VM's IP address to be migrated.  Once that
+happens, you will need to either restart your AFS client, or (perhaps
+more easily in some cases) turn your VM off and then back on (note that
+a reboot will not result in a functioning network connection; the very
+first time that you restart your VM after its IP migration, you must do
+so by completely turning off the VM and then turning it back on).  If you
+are curious about the technical reasons for this, see the next paragraph.
+You do not need to contact us about this.
+
+Restarting the AFS client after you are renumbered is necessary because
+after your AFS client starts up, the first time it talks to each of
+the fileservers in the AFS cells you use, it registers a list of the
+IP addresses it has with those fileservers.  That list will not be
+updated when your VM's IP address changes (there is a command
+`fs setclientaddrs` to change the list of IP addresses that will be
+sent to fileservers your client has not yet communicated with, but
+it will not update the addresses on file with servers your VM *has*
+already communicated with).  This will make the fileservers unable
+to inform your VM when changes have been made to files once the
+temporary NAT is removed, and you will begin to experience mysterious
+problems with AFS.
+
+## My VM runs daemons that have my IP address hardcoded in their configuration files.  What should I do?
+
+If at all possible, you should reconfigure them not to have IP addresses
+hardcoded.  If you're able to do that, you won't need to get in touch with
+us.
+
+If any of your daemons cannot work without a hardcoded IP address, you will
+need to get in touch with us at <xvm@mit.edu> to coordinate a time to
+migrate your VM's IP address.  Even though we will continue to send traffic
+for the old IP address to your VM for a period of time after its migration,
+we will do this with a NAT (essentially, we will take packets destined for
+your VM's old IP address, and we will change the destination address on them
+to the new address); your VM will only have an interface set up for the
+new address, and any daemons that try to make use of the old address in
+their configurations will encounter errors.
+
+We will work out a time with you when your IP address can be migrated.
+At that time, we will set your VM to migrate, and you will change the
+configuration files for your daemons.  Once the machine's IP address
+migrates, you will restart the daemons or turn your server off and then
+back on (note that a reboot will not result in a functioning network
+connection; the very first time that you restart your VM after its IP
+is migrated, you must do so by turning it completely off and then back on).
+
+## Should I contact you about my VM's renumbering?  When do I need to contact you by?
+
+If you have questions that are not answered by this FAQ, you should
+contact us and we'll do our best to answer them.  If your VM requires
+special coordination (for example, due to any of the reasons listed in
+the "Do I need to take any action?" question near the top of this page),
+you should definitely contact us no later than Sunday, June 3.  If anything
+goes wrong during your VM's migration, again, we need to hear from you.
+Finally, if you have feedback about the process that you would like to share,
+we welcome you to contact us.
+
+If none of the above applies to you, we hope that your migration experience
+is very smooth, and there is no need for you to get in touch with us.  Please
+keep in mind that, while we will do our best to answer messages that we
+receive, there are approximately 1,200 VMs that we need to get migrated in
+a very short time, and our resources are limited, so there is no need to
+contact us just to acknowledge receipt of the announcement or to report that
+your VM's migration was successful.
+
+