Using the self-serve net installer

From BitFolk
(Redirected from Self-install)
Jump to navigation Jump to search

For most guest operating systems it is possible for customers to launch a self-service network installer from the Xen Shell.

Default image installs vs. network installer

Most BitFolk customers have their VPS initially provisioned by BitFolk support via an image file. This results in a minimal install fully-customised for the BitFolk environment, but with very little flexibility.

Some customers prefer to run through their chosen operating system's familiar network installer in order to carry out a custom install to their specification. This can also be useful to reinstall your VPS without requiring assistance from BitFolk support.

Not all operating systems that BitFolk supports are available as self-service network installs. It requires that the operating system has a Xen-compatible network installer, and that this has been tested by BitFolk.


In order to initiate a network install you must:

  • Have access to your Xen Shell.
If you don't know the password then you'll need to do a reset or contact BitFolk Support.
  • Be running a new enough version of Xen Shell.
Xen Shell stays running if you disconnect from it, so it's possible that you're still running an old version. You need to be running version v1.48bitfolk8 or later. Different installers for different Linux distributions were added over time. See below to find out at what version of the Xen Shell an installer was added.
You can see the version of a running Xen Shell instance by using the help command. If yours is too old just exit from every screen until you're disconnected, and then reconnect.
  • Have a modern enough VPS configuration.
You may be warned that your VPS's disk layout is non-standard. In that case you'll need to use the reset command of the disks sub-menu to standardise it.
  • Be prepared to nuke your existing VPS and any data stored on it.
Generally the first thing the network installers do is format your VPS's block device(s), so don't try to do this unless you have backups or don't care about your data. It might be possible depending on the installer to preserve the contents of some block devices, but please don't rely on this.

Initiating a network install

Use the install command. It's as simple as:

xen-shell v1.48bitfolk2 - type 'help' for help.
xen-shell> install debian_lenny
About to overwrite your VPS with the debian_lenny network installer - this will result in a loss of all data, without further confirmation!
Are you sure? Please type "Yes" to confirm, or anything else to abort.
Booting debian_lenny net installer for: debtest1
Using config file "/etc/xen/debtest1.conf".
Install Mirror:
Install Suite: lenny

WARNING: Installer kernel and ramdisk are not authenticated.


The network installer should then boot and you'll follow the usual procedure for installing your chosen operating system.

General issues to be aware of


For later ease of resizing it is recommended that you restrict yourself to one partition per disk. The typical BitFolk VPS has two disks, xvda and xvdb each of which has a single partition spanning the whole disk (xvda1 and xvdb1 respectively). xvda1 would normally be the root filesystem and xvdb1 would usually be used for swap. If you require more partitions then you can add them via the disks sub-menu of the Xen Shell prior to install. This will give you extra disks, e.g. xvdc, xvdd and so on. You can split your disk allocation up into as many disk devices as you like.

If you don't do this and instead put multiple partitions on a disk it will still work fine, but if you should ever come to want a disk resized it makes the process more difficult.

Consider using LVM if you plan to have a lot of different filesystems and/or plan to do frequent resizing. As long as you keep the partition with /boot on it outside of LVM it works fine.

OS-specific notes


So far supported:

  • 12.x (bookworm) from v1.48bitfolk74
Note that as of this release udev has learned about Xen virtual Ethernet devices and so will by default rename your eth0 to enX0. Our installer will correctly set up your /etc/network/interfaces file for this device name. This is not specific to BitFolk or Xen; it's a consequence of the usual "predictable names" scheme. For more information please see the Debian Wiki.
  • 11.x (bullseye)
  • 10.x (buster)
  • 9.x (stretch)

Also, experimentally:

  • testing (trixie)

The installation process is pretty much identical to a normal Debian net install, with the following quirks.

Disk partitioning

The first partman dialog you'll be shown looks like this:

  ┌────────────────────────┤ [!!] Partition disks ├─────────────────┐
  │                                                                         │ 
  │ The installer can guide you through partitioning a disk (using          │ 
  │ different standard schemes) or, if you prefer, you can do it            │ 
  │ manually. With guided partitioning you will still have a chance later   │ 
  │ to review and customise the results.                                    │ 
  │                                                                         │ 
  │ If you choose guided partitioning for an entire disk, you will next     │ 
  │ be asked which disk should be used.                                     │ 
  │                                                                         │ 
  │ Partitioning method:                                                    │ 
  │                                                                         │ 
  │          Guided - use entire disk                                       │ 
  │          Guided - use entire disk and set up LVM                        │ 
  │          Guided - use entire disk and set up encrypted LVM              │ 
  │          Manual                                                         │ 
  │                                                                         │ 
  │     <Go Back>                                                           │ 
  │                                                                         │ 

You're advised to select Manual so that you can ensure that your root filesystem goes on xvda1 and your swap goes on xvdb1 as per the notes above. Using a filesystem label is also smart.

If using a separate /boot (commonly-needed for more complicated filesystem layouts, LVM, etc.) then please note that it has been observed that an i686 install of Debian jessie (8.x) with a 20MiB /boot failed due to lack of space while installing the kernel (actually while creating the initramfs), whereas the same install with a 25MiB /boot succeeded. A few megabytes could possibly be shaved off by telling it to build a targeted initramfs instead of a generic one (untested).

Once you've selected Finish partitioning and write changes to disk the installation will proceed as normal. If you don't select any additional software it should only take a few minutes.

Finishing the install

At the end you'll see:

   ┌────────────┤ [!!] Finish the installation ├────────────────────┐
  ┌│                         Installation complete                         │ 
  ││ Installation is complete, so it is time to boot into your new system. │  
  ││ Make sure to remove the installation media (CD-ROM, floppies), so     │  
  ││ that you boot into the new system rather than restarting the          │  
  ││ installation.                                                         │  
  ││                                                                       │  
  └│     <Go Back>                                          <Continue>     │  
   │                                                                       │  

Normally at this point you'd select <Continue> and your machine would reboot into your new install. Under Xen though, a reboot does not fully destroy the virtual machine. If the installer did do a reboot here, all that would happen is that Xen would restart the installer again. For that reason the installer has been set to halt here. You'll be dropped back to the Xen Shell prompt, and issuing a boot command will boot up your new VPS:

The system is going down NOW!ystem...                                       │ 
Sending SIGTERM to all processes                                            │ 
Sending SIGKILL to all processes─────────────────────────────────────┘ 
Requesting system halt                                                        
                      [ 4298.952440] md: stopping all md devices.
[ 4299.944797] xenbus_dev_shutdown: device/console/0: Initialising != Connected, skipping
[ 4300.295265] System halted.
xen-shell> boot
Booting instance: debtest1

    pyGRUB  version 0.6
 x Debian GNU/Linux, kernel 2.6.26-2-xen-686                              x
 x Debian GNU/Linux, kernel 2.6.26-2-xen-686 (single-user mode)           x

Started domain debtest1
                       [    0.000000] Initializing cgroup subsys cpuset
[    0.000000] Initializing cgroup subsys cpu
[    0.000000] Linux version 2.6.26-2-xen-686 (Debian 2.6.26-26lenny1) ( (gcc version 4.1.3 20080704 (prerelease) (Debian 4.1.2-25)) #1 SMP Thu Nov 25 02:32:31 UTC 2010

Things you might like to change after install

By this point you've just completed a fresh install of Debian and it should be working fine, but you won't have some of the nice features of a typical BitFolk VPS image configured. Things you may wish to look into:

  • You either won't have an NTP server installed or else it won't be configured to talk to the NTP servers.
  • /etc/resolv.conf will only have one of the two BitFolk DNS resolvers.
  • Your /etc/fstab will be mounting things by device name, but it's recommended to change that to UUID or label. Future changes to the Linux kernel are more likely to rename virtual block devices than devices for regular SATA disks, so it's wise to make sure that things mount properly even if this should happen.
  • If your VPS has multiple IPv4 addresses then only the first one will have been configured by the installer.
  • The installer may not have set up IPv6 at all, or may have done so automatically. You may need to set this up how you prefer.

Breaking out of the installer

If you do something wrong then you can generally fix it by going back to the installer's main menu. You get there by selecting Go back when given that option in a dialog. From the main menu of the installer you can retrace your steps. You can also start a shell if you need to poke around.

You can of course always create a new Xen Shell window, shutdown or destroy your running installer VPS and just start over again.

Saving logs

If you're having problems then showing BitFolk Support the logs from your installer will be helpful. There is a "Save debug logs" option near the end of the main menu of the installer which will create a directory with the logs in it. Available options for saving the logs are:

  • Floppy
    Which quite clearly doesn't make sense on a VPS.
  • Web
    Which will start a web server on your VPS's IP address with access to the log files so you can download and save elsewhere.
  • Mounted file system
    Which will let you save the logs somewhere in the installer VM.

The easiest way to get the logs off is probably the Web choice, as you can just point your web browser at the VPS's IP and download the files.

Next easiest would probably be to enable SSH support in the installer and then use the Mounted file system option to save the logs somewhere (e.g. /mnt as it suggests would be fine), start a shell and scp them out. To enable SSH in the installer:

  1. Use the "Change debconf priority" option to change priority to low.
  2. Use the "Download installer components" to select openssh-client-udeb.

Now when you use the "Execute a shell" option you should have ssh and scp commands available.

Another possibility would be to use the Mounted file system option to save the logs somewhere inside the system being installed, which is somewhere under /target from the point of view of the installer, e.g. /target/var/tmp. You would then boot into the rescue VM to access the logs, copy them elsewhere, etc.


Main article: Ubuntu

Currently supported:

  • 22.04.x LTS (Jammy Jellyfish) from v1.48bitfolk73
  • 20.04.x LTS (Focal Fossa) from v1.48bitfolk58
Note that from 19.10 Ubuntu have switched to LZ4-compressed kernels which when run in Xen PV mode require a workaround script be installed in order to work at BitFolk. BitFolk recommends running in PVH mode (which as of November 2020 is the default) where this works fine, but if you stick with PV mode then the installer adds the workaround for you.
  • 18.04.x LTS (Bionic Beaver) from v1.48bitfolk46
Note that from 18.04 Ubuntu have switched to using netplan to configure the network, and Ubuntu installers from 18.04 onwards will reflect this.
  • 16.04.x LTS (Xenial Xerus) from v1.48bitfolk36

Starting with Ubuntu 22.04 the install process is the official Ubuntu Cloud Image, customised at first boot for your BitFolk account with cloud-init.

Prior to Ubuntu 22.04 the process is largely identical to Debian as it uses the Debian installer.

Check out our article on Ubuntu for additional notes.

Here's a screencast of someone installing 11.04 on a BitFolk VPS.

CentOS Stream

Main article: CentOS Stream

So far supported:

  • CentOS Stream 9.x (from v1.48bitfolk75)
  • CentOS Stream 8.x (from v1.48bitfolk63)
  • CentOS Linux 7.x (from v1.48bitfolk37)
Warning Warning: CentOS 8 has dropped support for PV and PVH mode Xen guests even though the upstream Linux kernel supports that by default. Therefore the CentOS Stream installer will use the kernel-lt kernel from ELRepo.

Things you might like to change after install

  • If your VPS has multiple IPv4 addresses then only the first one will have been configured by the installer.
  • The CentOS 7.x installer won't have set up IPv6 at all. This was fixed for the CentOS 8.x installer.
  • A default firewall configuration has been loaded; this will likely need to be modified if you're going to run any public network services.

Arch Linux

A guide has been written up for installing Arch Linux via the Rescue VM.

Fedora Linux

A guide has been written up for installing Fedora Linux via the Rescue VM.


A guide has been written up for installing Gentoo via the Rescue VM.


A guide has been written up for installing NixOS via the Rescue VM, with a system closure built on a separate machine.


A guide has been written up for installing Slackware via the Rescue VM.

Other unsupported Linux distributions

Since the upstream Linux kernel supports booting as a Xen guest it is usually possible to install any distribution through the Rescue VM. We have some additional notes on installing unsupported distributions which may help.