# v2.0.0

Komodo v2 is a major release with significant architectural changes and new features.

## Changelog

- **Docker Swarm support**: Manage swarm clusters, nodes, services, stacks, configs, and secrets.
- **Outbound periphery**: Periphery can now initiate the connection to Komodo Core.
- **PKI authentication**: Core and Periphery now authenticate with auto-generated key pairs and automatic rotation. Passkeys are deprecated.
- **Onboarding keys**: streamlined server onboarding with reusable keys.
- **Improved terminals**: Terminals dashboard, `km ssh`, and improved Action scripting.
- **Improved auto updates**: Uses a better system to handle auto updates based on image digest.
- **New UI**: Improved look with higher contrast and better UI primitives.
- **Passkey / TOTP 2FA**: Built in two factor authentication for username / password login.
- **Multi-login Linking**: Users can now link multiple login providers (Local, OIDC, Github, etc) to their account.
- **Full OpenAPI documentation**: Interactive API docs [now available](https://demo.komo.do/docs).

### 🚨 Breaking

- **Debian Bullseye EOL**: Bullseye stopped recieving security updates in 2024 and is slated to be EOL. The binaries are now built with Debian Bookworm which uses openssl v3,
and Periphery may have compatibility issues running on systems running **openssl v1** including **Debian Bullseye / Ubuntu 20.04 and before**. You can still compile Periphery
yourself for these systems if needed (or use containerized periphery), but the official distribution will use the more secure and up-to-date option.

## Upgrading to Komodo v2

Komodo v2 introduces a new connection and authentication method between Komodo Core and the Periphery agents running on your Servers. Find more information on [Komodo v2 here](../releases/v2.0.0).

It is largely backward compatible with Komodo v1 configuration, and users can upgrade from v1 in place by following the steps below.

:::note
Starting with v2, Komodo will not publish images with the `latest` tag in favor of Semver (`2`, `2.0`, `2.0.0`).
This prevents unintented major version upgrades when using auto updaters. Use `:2` to stay up to date
with all future Komodo v2 releases.
:::

### 1. Upgrade Core and Periphery to v2

The first step is to upgrade **both Core and Periphery** to v2 versions, along with **some small configuration changes**.

#### Upgrade Core

In the Komodo Core compose service, **update the image to `:2` tag**, and **add a new mount to `/config/keys`**.

```yaml
services:
  core:
    image: ghcr.io/moghtech/komodo-core:2
    init: true # This should be added regardless of version
    volumes:
      - keys:/config/keys
      - (...unchanged)
    (...unchanged)

volumes:
  keys:
  (...unchanged)
```

:::warning
Ensure the Komodo Core service **and** all Periphery services / containers include `init: true`,
as shown above. Failing to do so may cause a build up of zombie processes,
and it wasn't included in earlier releases example compose file.
:::

#### Upgrade Periphery: Container

If you are running Komodo Periphery in a container, you also need the `:2` tag for the image,
and the keys will default to being stored in `/config/keys`.

```yaml
services:
  periphery:
    image: ghcr.io/moghtech/komodo-periphery:2
    init: true # This should be added regardless of version
    volumes:
      - keys:/config/keys
      - (...unchanged)
    (...unchanged)

volumes:
  keys:
  (...unchanged)
```

#### Upgrade Periphery: Systemd

Systemd Periphery users just need to update their Periphery binary version. The keys will be stored in your `root_directory` (default: `/etc/komodo/keys`).

After getting both Core and Periphery running, everything should already work correctly at this point.

### 2a. Move to public key authentication

If you want to **reverse the agent connection, [skip this step and go to 2b](#2b-reversing-the-agent-connection)**.

If you want to keep the Core to Periphery connection direction, you can increase the security by
**moving from passkey authentication to public key authentication**.

Navigate to the `Settings` page, at the top you will find the Core Public Key (starting with `MCow...`).
Copy this key and and **redeploy Periphery agents with updated configuration**:

```toml
## Accepted public keys to allow Core(s) to connect.
## Periphery gains knowledge of the Core public key through the noise handshake.
## If neither these nor passkeys provided, inbound connections will not be authenticated.
## Accepts Spki base64 DER directly and PEM file. Use `file:/path/to/core.pub` to load from file.
## Env: PERIPHERY_CORE_PUBLIC_KEYS
## Optional, no default.
core_public_keys = "<YOUR_CORE_PUBLIC_KEY>"
```

After confirming the connection still works, you can remove any legacy `passkey` configuration for both Core and Periphery as it is no longer needed.

### 2b. Reversing the agent connection

The Periphery agent is now able to establish an outbound connection to Komodo Core.
After updating to Komodo v2, **you can follow these steps to migrate to outbound connections
using public key authentication**. Note you must be an Admin user on Komodo.

1. (**Periphery container only**.) Ensure the automatically generated private keys are persisted by mounting to the `/config/keys` of the Periphery container, as noted above.
2. Navigate to `Settings / Onboarding` and create a new **onboarding key**. Save it for later.
3. Enable **privileged mode** on the new Onboarding Key.
4. **Redeploy Periphery agents with updated configuration:**

```toml
## The address of Komodo Core. Must be reachable from this host.
## If provided, Periphery will operate in outbound mode.
## Env: PERIPHERY_CORE_ADDRESS
## Default: None
core_address = "<YOUR_KOMODO_CORE_ADDRESS>" # Example: demo.komo.do, ws://localhost:9120

## The Server this Periphery agent should "connect as".
## Systemd periphery can use the system hostname by setting `connect_as = "$(hostname)"`.
## Env: PERIPHERY_CONNECT_AS
## Default: None
connect_as = "<SERVER_NAME>"

## Make Onboarding Keys in Server settings.
## Not needed if connecting as Server that already exists.
## Env: PERIPHERY_ONBOARDING_KEY
onboarding_key = "<YOUR_ONBOARDING_KEY>"
```

Upon connecting, the privileged onboarding key will allow the existing server's expected public key
to be updated, allowing the Periphery agent to connect.
**In general when onboarding _new_ servers, privileged mode is not needed.**

### 3. Fix any `komodo.execute_terminal` in Actions

:::info
If you don't know what this is, you don't need to do anything. **Congratulations, you are done.**
:::

Rename `execute_terminal` -> `execute_server_terminal`.

So in v1 Action:

```ts
// This took 2 calls in v1
await komodo.write("CreateTerminal", {
  server: "my-server",
  name: "my-terminal",
  command: "bash",
  recreate: "Always",
});
await komodo.execute_terminal(
  { server: "my-server", terminal: "my-terminal", command: "ls -l" },
  { onLine: (line) => console.log(line) },
);
```

In v2 becomes:

```ts
// Streamlined terminal execute with init options.
await komodo.execute_server_terminal(
  {
    server: "my-server",
    terminal: "my-terminal",
    command: "ls -l",
    init: { command: "bash", recreate: "Always" },
  },
  { onLine: (line) => console.log(line) },
);
```
