# Dedicated Bare Metal

## API Token

1. Generate an API token, the procedure is documented in [API v3 Authentication](https://docs.i3d.net/game-hosting/overview/apiv3-authentication)
   1. Add IP whitelisting for security (whitelist the IP addresses that will access the API)
2. Include your API key in every request using this **HTTP header**:

   | HTTP Header Name | HTTP Header Value |
   | ---------------- | ----------------- |
   | PRIVATE-TOKEN    | YOUR\_API\_KEY    |
3. Throughout these documentation pages, we will refer to API endpoints like for instance:

   `GET /v3/host`

   \
   This is not a complete endpoint. You must prefix this with the API URI and API version tag:

   `https://api.i3d.net/v3/`

   \
   That results in the complete URL:

   `GET https://api.i3d.net/v3/host`

{% code title="Example HTTP request:" %}

```
GET /v3/host
Host: api.i3d.net
PRIVATE-TOKEN: abc123xyz789
```

{% endcode %}

## Server details

The host endpoint provides details on dedicated bare metal servers in your account.

To list all Hosts with full detail on hardware configuration including IP addresses:

[`GET /v3/host`](https://docs.i3d.net/api/api_one#v3-host-hostid)

To list details of a specific Host:

[`GET /v3/host/{hostId}`](https://docs.i3d.net/api/api_one#v3-host-hostid)

## Server actions

Basic action for power On/Off/Restart can be performed on each server using below endpoints:

Turn the server On: [`PUT /v3/host/{hostId}/start`](https://docs.i3d.net/api/api_one#put-v3-host-hostid-start)

Turn the server Off: [`PUT /v3/host/{hostId}/stop`](https://docs.i3d.net/api/api_one#put-v3-host-hostid-stop)

Restart the server: [`PUT /v3/host/{hostId}/restart`](https://www.i3d.net/docs/api/v3/game-publisher#/Host/updateHostRestart)

## Server OS installation

This endpoint allows the installation of a new operating system onto a server in the customer account.

The `{hostId}` parameter can be found in [`GET /v3/host`](https://docs.i3d.net/api/api_one#get-v3-host) which lists all the servers in your account.

### API endpoint

Trigger an OS installation: [`POST /v3/host/{hostId}/os/install`](https://docs.i3d.net/api/api_one#post-v3-host-hostid-os-install)

Check the current status of the installation process: [`GET /v3/host/{hostId}/os/installLog`](https://docs.i3d.net/api/api_one#get-v3-host-hostid-os-installlog)

You will need to know which Operating System id to use by using below endpoint:

[`GET /v3/operatingsystem`](https://docs.i3d.net/api/api_general#get-v3-operatingsystem)

#### Request body properties

<table><thead><tr><th width="172.88671875">Property</th><th width="116.203125">Value type</th><th width="105.27734375">Required</th><th>Description</th></tr></thead><tbody><tr><td>hostname</td><td>string</td><td>Optional</td><td>Default is <code>Server{ID}</code> with Unique identifier. NOTE: when installing Talos, the machine name will be derived from the hostname, taking the first part of the hostname.</td></tr><tr><td>os.id</td><td>int</td><td>Required</td><td>Desired os.id look up in <a href="https://docs.i3d.net/api/api_general#get-v3-operatingsystem"><code>GET /v3/operatingsystem</code></a></td></tr><tr><td>os.kernelParams</td><td>string</td><td>Optional</td><td>An advanced option, currently only applies when installing Talos (See talos OS section)</td></tr><tr><td>postInstallScript</td><td>string</td><td>Optional</td><td>Optional bash script to be performed after OS installation. Does not apply to Talos.</td></tr><tr><td>sshKeyId</td><td>UUid</td><td>Required</td><td>Manage your SSH keys via <a href="https://docs.i3d.net/api/api_general#post-v3-sshkey"><code>POST /v3/sshKey</code></a>. The public key will be installed for the root user.</td></tr><tr><td>quickFormat</td><td>bool</td><td>Optional</td><td>Optional parameter indicating whether you want the disks to first be quick-formatted prior to OS installation. We recommend to always perform a quick-format, unless you have a specific case where it is not needed to clear the disk partitions prior to installing a new OS.</td></tr></tbody></table>

Table 1: Install OS element structure

#### Example request

[`POST /v3/host/{hostId}/os/install`](https://docs.i3d.net/api/api_one#post-v3-host-hostid-os-install)

Request Body

```json
{
  "hostname": "my.host.name",
  "os": {
    "id": 261
  },
  "postInstallScript": "#!/bin/bash\necho \"Hello world\" > /tmp/test.txt",
  "sshKeyUuid": "62335584-bee9-48a2-xxxx-3561d8cadad1",
  "quickFormat": true
}
```

### Talos OS

Talos is a stripped down Linux distribution tailored towards easy setup and management of Kubernetes clusters.

Sidero [Talos](https://www.talos.dev/) allows you to create a Kubernetes cluster, using [Omni](https://www.siderolabs.com/omni/) as the central administration hub. To connect Talos nodes to Omni, a [join token](https://www.talos.dev/v1.10/talos-guides/network/siderolink/) needs to be passed to the node. This configuration parameter is referenced as a `siderolink.api` URL.

i3D.net currently only support Talos installations that connect to Omni. Therefore a `siderolink.api` URL must always be provided by means a kernel argument injected into the API call for a vanilla Talos install, or injected into a [Talos Factory image](https://factory.talos.dev/).

Talos can be installed in two flavors, using a vanilla image or using a Talos Factory image:

* Talos install vanilla: provide required `siderolink.api` link
* Talos install via Factory image: provide required `factoryhash`

### Example Talos OS Vanilla Request Body

[`POST /v3/host/{hostId}/os/install`](https://docs.i3d.net/api/api_one#post-v3-host-hostid-os-install)

You must provide a `siderolink.api` URL as a kernel argument in the API request body. This makes the Talos node join your Omni instance.

You can provide additional Talos kernel arguments in the request body complementing or overriding our defaults.

```bash
slab_nomerge
pti=on
vga=normal
locale=en_US
console-keymaps-at/keymap=us
net.ifnames=0
panic=0
initrd=initrd.magic
init_on_alloc=1
consoleblank=0
nvme_core.io_timeout=4294967295
nvme_core.multipath=n
printk.devkmsg=on
ima_template=ima-ng
ima_appraise=fix
ima_hash=sha512
talos.platform=metal
talos.events.sink=[fdae:41e4:649b:9303::1]:8091
talos.logging.kernel=tcp://[fdae:41e4:649b:9303::1]:8092
```

More information about Talos kernel parameters you can find here: <https://www.talos.dev/v1.11/reference/kernel/>

Our systems will automatically inject network configuration for your server.

**Request body**

```json
{
  "hostname": "My.Host.Name",
  "os": {
    "id": 294,
    "kernelParams": [
      {
        "key": "siderolink.api",
        "value": "https://path.to/omni?bcwe7r8236r7gwuyiwe"
      },
      {
        "key": "talos.customparam",
        "value": "123456"
      }
    ]
  },
  "postInstallScript": null,
  "sshKeyUuid": "62335584-bee9-48a2-a81d-3561d8cadad1"
}
```

### Example Talos OS Factory Request Body

[`POST /v3/host/{hostId}/os/install`](https://docs.i3d.net/api/api_one#post-v3-host-hostid-os-install)

You must provide a `factoryhash` as a kernel argument in the request body, pointing to the Factory image you want to use.

You should add all your kernel arguments inside of the Factory Image configuration, and not add any here in the request body, as they will be forgotten by Talos when you add a node to a cluster, or upgrade a node.

**Request body**

```json
{
  "hostname": "My.Host.Name",
  "os": {
    "id": 294,
    "kernelParams": [
      {
        "key": "factoryhash",
        "value": "93be9c834b04065cdfb6223049697263586e92471231ed2abdfcc23c2a4551a4"
      }
    ]
  },
  "postInstallScript": null,
  "sshKeyUuid": "62335584-bee9-48a2-a81d-3561d8cadad1"
}
```

{% hint style="info" %}
**Note:** When installing Talos, it relies on an external site. If the external site is down, installation cannot proceed.
{% endhint %}

### Classic NIC names vs predictable NIC names <a href="#classic-nic-names-vs-predictable-nic-names" id="classic-nic-names-vs-predictable-nic-names"></a>

The kernel parameter `net.ifnames=0` will disable predictable network interface names and revert to classic names like `eth0`, `eth1`, etc.

**In most cases it is best practice to use `net.ifnames=0` so make sure you add that as a kernel argument to your Factory Image configuration.**

This works in most cases where a server only has 1 or 2 uplinks. If you have more than 2 uplinks and network configuration is failing, it can be that Talos is assigning the wrong interfaces to `eth0` and / or `eth1`. In that case you can try using the "[predictable interface names](https://wiki.debian.org/NetworkInterfaceNames)" solution, by using the kernel parameter `net.ifnames=1`.