Skip to main content

Setting Up an On-Premises Altra Deployment

Getting Started​

We refer to your setup of Corellium as your domain. Your domain contains users (including the administrator user), projects, teams, and virtual devices. Your domain must be assigned a human-readable name (e.g., the name of your company) and a machine-readable name (e.g., your-company.corellium.net).

Users access Corellium through a web interface. This web interface is served on the traditional HTTP and HTTPS ports 80 and 443 on the controller node (see Server Roles in Corellium).

Although users can access the web interface directly by the IP address of the controller node, it is preferred for you to configure their DNS settings so that they may access it through the domain name (e.g., your-company.corellium.net).

Note that although we give “corellium.net" as the example suffix for your domain name, we do not and cannot actually publish the local, private IP address of your Corellium controller node to public DNS, so you must add that as an entry in your private DNS.

Corellium requires HTTPS. A self-signed certificate is automatically generated and must be accepted by your users. Alternatively, you may provide a certificate and key for Corellium to use.

Virtual Devices​

Virtual devices are the core of Corellium (pun intended).

Virtual devices each have a virtual interface that they can use to access the outside world. Corellium has its own internal DHCP server that exclusively gives IPs to virtual devices. In addition to the IP assigned to the virtual device’s wi-fi interface, Corellium also allocates a per-device IP that users can interact with the device with. Many services are hosted on this per-device IP, such as the ability to connect USB devices to the virtual device using USBIP.

The simplest way to configure Corellium is to have Corellium use a DHCP server you already have setup on your network to determine the IP addresses to use for the Wi-Fi and service IPs. This has the drawback of having each device have semi-randomly assigned IP addresses that are not memorable.

Corellium can also be used in virtual device static IP mode. In this mode, each project in Corellium has its own /23 IP space, and virtual devices within the project are assigned addresses within that /23 IP space. For example, if the project has the IP space 10.11.2.0/23, the first virtual device would have a wi-fi IP of 10.11.2.1 and a services IP of 10.11.3.1.

In other words, each project is given a consecutive range of 512 IP addresses, starting from an IP address whose 3rd part must be an even number. For example, 10.11.4.0 would be a valid starting address for the project’s range, but not 10.11.5.0.

This system makes it easy for users to quickly remember the IP addresses of their devices and be able to easily access them with their tools, streamlining their process.

Projects​

Virtual devices are organized into projects. Projects are the basic resource allocation and access control units in Corellium. Users are created by the administrator and given permission to access projects. Projects are assigned certain amounts of resources by the administrator and users with permission to access projects can freely use them to create virtual devices.

The more projects you wish to add to Corellium, the greater amount of IP space Corellium will need in virtual device static IP mode. Before installing Corellium, you must estimate how many projects you will need to create and figure out how much IP space (and where) to assign to Corellium’s projects. For more discussion on this, see Virtual Device Network in the Networking in Corellium section.

Corellium allocates the IP ranges for each project, starting from a value you, the administrator, configures. For example, if you configure 10.15.14.0, the first project created will have a range of 10.15.14.0 -> 10.15.15.255, the second will have a range of 10.15.16.0 -> 10.15.17.255, etc. Note that because of this, Corellium needs one contiguous IP space for its projects and virtual devices.

Server Roles​

There are two possible roles in Corellium: The compute role and the controller role. Each server (or node) can take on one or more of these two roles. Note that in some cases, one physical chassis can contain two logical servers (e.g., when we ship what is called “dual-node” servers). In this case, each logical server (or node) must be treated as an entirely separate server.

Nodes that serve the compute role are the ones that actually run the virtual devices. These nodes necessarily have to be ARM servers running our proprietary hypervisor.

Nodes that serve the controller role are the ones that run the front-facing Corellium software. Compute nodes report to the controller nodes, which coordinate the cluster. The controller nodes take care of the allocation and scheduling of virtual devices onto the compute nodes. They also store the virtual device firmware and serve it to compute nodes that request them. They also store custom kernels and other images uploaded by users.

In the Multi-Node setup, Corellium configures one of the servers to be a controller node as well as a compute node. It comes equipped with extra disks in order to store the large virtual device firmware files.

The Controller Node will be your single point of contact with the Corellium software. It runs the Corellium user interface. Additionally, the Controller Node can be used to upgrade, reconfigure, or reset Corellium if necessary since it contains credentials necessary to alter the other servers.

In the Single-Node setup, Corellium configures the same server to be both a controller node and a compute node. When we refer to the Controller Node in the document, we are referring to that server, even though it serves both as a controller and a compute node.

Networking​

Corellium servers are all connected together on a single Layer 2 network. The 1GB port on the Corellium server should be connected to a switch.

On Layer 3, Corellium uses two networks: the virtual device network and the control network. It is possible for Corellium to be configured in such a way that the two are in fact the same Layer 3 network. Configuring both networks to be the same network as the main network users are on allows users to easily access both the Corellium user interface and their virtual devices. However, Corellium requires large blocks of IP addresses, so this setup is not always practical.

Corellium uses static IP addresses and large blocks of IP space for virtual devices, so a network administrator is required to setup Corellium.

Control Network​

The control network is how nodes communicate with each other and the outside world. The controller node runs a web server listening on the traditional ports of 80 and 443. This web server is the one users use to access the Corellium UI. The IP address assigned to each node must be static and fixed at the time Corellium is configured since Corellium discovers and identifies itself through these IP addresses.

Each Corellium server needs a static IP address, netmask, and optionally a gateway. The netmask determines what Layer 3 network the server will be on. The gateway allows Corellium servers to reach external addresses. This is required if Corellium is on a different network than users or if virtual devices are required to be able to reach the Internet. Optionally, DNS servers may be specified to allow Corellium servers to access the Internet in order to download updates for virtual device firmware and Corellium software. All Corellium servers share the same netmask, gateway, and DNS Servers.

Since each node identifies and authenticates itself to each other using its IP address, changing the IP addresses of Corellium servers will require a reset of the entire Corellium setup.

It is up to you to decide which IP addresses, netmasks, and gateways to assign to the servers on the network. We recommend placing Corellium on your main internal network for ease of configuration and access and configuring your DHCP server to honor a static reservation for the Corellium servers. To make things a bit easier, we’ve included the MAC Address in your Initial Networking Configuration and Passwords document.

Once you have determined which IP addresses to give the Corellium servers, you must make provisions for your users to be able to access the Corellium Controller Node.

First, users must be able to access the Corellium control network. This can be done by merely placing Corellium on the same network users use (e.g. your main internal network). If you wish to put Corellium on another network, you must configure the router on your main internal network to route packets to and from the Corellium control network to and from your main internal network.

For example, you could plug the router physically into both the Corellium control network and your main internal network. You would assign an IP address on the router on your main internal network and an IP address on the router on the Corellium control network.

Then you could enable IP forwarding on the router to transfer packets between the networks. This setup would work as long as machines on the main internal network use the router’s main internal network IP address as their gateway and you configured Gateway under Networking Information in Corellium to be the router’s Corellium control network IP address.

Second, users must be able to discover and access the Corellium Controller Node. If your organization has its own internal DNS server, you could configure the DNS server to return the IP address of the Corellium Controller node when users request a certain domain name. You could also ask users to put the domain name into their /etc/hosts file, or access the Corellium Controller Node by its IP address directly.

Virtual Device Network​

The virtual device network is the network all the virtual devices are on. For our on-premise setups, all the virtual devices are on a single network. The simplest way to configure Corellium is to have Corellium use a DHCP you already have setup on your network to determine the IP addresses for virtual devices to use on the network. This has the drawback of having virtual devices get semi-random IP addresses that are not organized or memorable.

A more organized way to do it is to assign a specific range of static IP addresses to Corellium. As described above in Projects and Devices, virtual devices are assigned IPs from their project’s range of IPs. The projects themselves are assigned ranges based on the “Virtual Devices IP Address” setting in the configuration.

In addition to configuring the network range via the Virtual Devices IP address and Virtual Devices Netmask, a gateway can be configured to allow virtual devices to reach external addresses. If you are not putting the virtual devices on the same network as the users, the gateway will be required for users to access the virtual devices. If not and internet access for virtual devices is not required, then the gateway is not required.

Note that the gateway is not a “virtual gateway”. It is a gateway for virtual devices. The gateway is not a facility Corellium provides or configures. It is something a network administrator must provide and configure as its configuration must be specific to the network of each organization.

For similar reasons, Corellium also cannot provide DNS servers for virtual devices to use. If you are configuring the network for virtual devices to access the public Internet, you may simply use public DNS servers such as 1.1.1.1 or 8.8.8.8 for this purpose.

It is not required that control network and virtual devices network be the same or be reachable from each other.

In static IP range mode, Corellium reserves the last IP address in the virtual device network, so it cannot be used as the IP address of the gateway for virtual devices.

It is up to you to decide which range of IP addresses you give to the projects. You can pick any range that does not conflict with your existing networks. However, you must make sure the range is large enough to accommodate all the projects you wish to create now and in the future. You must also make provisions for your users to access this network.

It is possible to place the Corellium virtual device network on the same network users use (e.g. your main internal network). This way, users could access the virtual device network, but you might be constrained on how large of a range you can assign Corellium.

If you wish to put the Corellium virtual devices on another network, you must configure the router on your main internal network to route packets to and from the Corellium virtual device network to and from your main internal network. For example, you could plug the router physically into both the Corellium virtual device network and your main internal network. You would assign an IP address on the router on your main internal network and an IP address on the router on the Corellium virtual device network.

Then you could enable IP forwarding on the router to transfer packets between the networks. This setup would work as long as machines on the main internal network uses the router’s main internal network IP address as their gateway and you configured Virtual Devices Gateway under Virtual Device Static Networking Information in Corellium to be the router’s Corellium virtual device network IP address. Again, Corellium does not provide the router/gateway required to connect the virtual device network to your main network in static IP mode, nor can Corellium configure it for you.

We recommend setting aside a /16 space for all of Corellium’s virtual devices and configuring your router to be able to route packets between that network and your main network. For example, you could setup Corellium’s Virtual Devices IP address to be 10.11.2.0, netmask to be 255.255.0.0. The first project will take up the range 10.11.2.0 -> 10.11.3.255. You could then put your router at 10.11.0.1 and the Corellium control network in the 10.11.0.2 -> 10.11.1.255 range.

If you will have multiple installations of Corellium, they may not share the same virtual device IP range. In this case, each installation of Corellium must have its own range (though they may be on the same network).

Port Mapping​

Cluster Installations​

On the Controller Nodes, Corellium uses the following ports: 22, 443, 444, 8080, 8086, 8088, 9091, and 27820.

On the Compute Nodes, Corellium uses the following ports: 22, 1234, 2000, 4000, 5037, 11111, and 27820.

Combined Installations​

Corellium uses the following ports: 22, 443, 1234, 2000, 4000, 5037, 8080, 8086, 8088, and 27820.

Hybrid Installations​

On the combined controller and compute node, Corellium uses the following ports: 22, 443, 444, 1234, 2000, 4000, 5037, 8080, 8086, 8088, 9091, 11111, and 27820.

On compute nodes, Corellium uses the following ports: 22, 1234, 2000, 4000, 5037, 11111, and 27820.

Setup and Updates​

Corellium is shipped configured to use a specific static IP address and netmask. In case the configured static IP address conflicts with your institution’s network, we advise you to complete the setup with Corellium machines not initially connected to your institution’s network. Corellium servers require the use of static IP addresses. Corellium servers cannot operate with DHCP. The Controller Node will output a setup URL on the serial console as it boots up, so it is advisable to have the serial console connected when booting the Controller Node for the first time.

Going to the URL provided will allow you to provide the configuration settings Corellium needs to set itself up. Even after Corellium is setup, on future reboots of the Controller node, the setup URL will be printed on the serial console, and still may be used to change configuration settings and rerun setup. It is also possible to completely reset Corellium using this interface if something goes wrong. After initial setup however, the setup interface will require the administrator’s username and password (which are configured during initial setup).

During reconfiguration, due to the fact that the authentication server itself needs to be brought down and setup again, the progress indicator may not be accurate. Setup will be complete when the controller node reboots.

We will provide you shell usernames and passwords to the root accounts of all the machines we send you, though we recommend not modifying the software configuration manually. SSH access via password authentication is enabled on all the machines.

If you have a Multi-Node setup, the Corellium controller node uses the SSH password authentication to connect to the other nodes in order to update and setup the configuration on each of them. The correct password to the root accounts of each node other than the controller node must be provided during updates and (re)configurations.

What's Included​

First up, here's what's included with your Ampere Altra Single-Node Server:

  • Processor: Ampere ARMv8.2-A 64-bit (80 total cores, 64 device cores, 3.0 GHz)
  • Form Factor: 2U Rack Server
  • Power Supply: Dual 2000W redundant
  • Memory: 128 GB (8× 16GB) RDIMM 3200
  • Hard Drives: 4× 4TB Micron 2.5” 7300 NVMe2× 2TB M2 Micron 2300
  • GPU: 1× NVIDIA T4
  • OS: Ubuntu 18.04
  • Dimensions: 26” × 19” × 3.5” Altra Server

Setting Up Your Stack​

Hardware​

1.Connect the 1GbE BMC (Management) port into your management network via an Ethernet cable. 2. Connect the top 1GbE port into your regular network. 3. Plug in the power to turn on the servers.

Note: servers can take 3-5 minutes to boot.

Software​

Go to IP and follow installer instructions

Obtain your Laptop IP Address, Netmask and Controller IP Address from the Initial Networking Configuration and Passwords document. Configure the laptop with the following networking information:

  • IP Address: Laptop IP
  • Netmask: Netmask
  • Gateway: <none or unspecified>
  • DNS: <none or unspecified>

In a command line on the laptop, enter:

ping [Controller IP Address]

Wait until the server starts responding, then use the web browser on the laptop to goto https://[Controller IP Address]:8088/. Then, do the following:

  1. Fill out the temporary Corellium UI username and password provided in the Initial Networking Configuration and Passwords document.
  2. Fill out the required information. For more details, please read the Installation Overview section. Make sure that the Networking Information and Virtual Device Networking section are completely filled out with correct information. The defaults for the other sections are acceptable.
  3. Click Reconfigure Corellium.

You may have to refresh the page from time to time to get updated progress information. Because you may have changed the servers’ networking information, the server may become unreachable during the process unless you also change your laptop’s networking information. In any case, the installation will proceed without the web browser being connected.

Wait for the process to finish and the servers to all reboot.

Finalize networking configuration​

You will need to set up DNS for the domain you chose during setup. This can be done by adding it to your institution’s DNS server, or by adding it as a static DNS entry in the hosts file on each laptop that will be accessing Corellium.

Physically connect the Corellium servers to your institution’s network.

Verify that the Corellium servers are reachable by ping through your institution’s network.

Log In​

  1. Navigate to the domain you chose during setup.
  2. Log in using the Corellium UI username and password. The initial ones are listed in the Initial Networking Configuration and Passwords document. If you changed the Administrator Password setting during setup, the password will be that instead.
  3. Create projects and users for your installation.

If you move the service IP, you have to delete the project and recreate it. The IP ranges assigned to projects happen when they’re created.

Getting Updates​

Corellium will provide updates to you via the Control Panel. The URL and login details can be found in your Initial Networking Configuration and Passwords document.

To install an update, download the update package file from the Control Panel.

  1. Transfer the Corellium upgrade (the .tar.xz tarball) to the Controller Node (e.g. via SCP) into the home directory of the root user (/root).
  2. SSH into the Controller Node.
  3. Over SSH, extract the Corellium upgrade via tar xvf <update name>.tar.xz. The files should all be extracted to /root/<update name>
  4. Change the directory into the top directory of the update: cd <update name>
  5. Start the updater: ./install.sh.
  6. Use the web browser on the laptop to go to the URL listed by install.sh.
  7. Fill out the required information. For more details, please read the Architecture Overview. Your settings should have transferred, but make sure they are correct.
  8. Click Upgrade Corellium.
  9. Wait for the process to finish and the servers to all reboot.

Further Reading​

We have some fantastic related guides available on getting the most out of your Corellium deployment, such as how to upload custom IPSWs. We also have a Support Center covering topics such as how to manage your devices, projects and teams. If you're stuck on something, check out our Troubleshooting and FAQs.