130 lines
3.7 KiB
Markdown
130 lines
3.7 KiB
Markdown
# Update Machines
|
||
|
||
The Clan command line interface enables you to update machines remotely over SSH.
|
||
In this guide we will teach you how to set a `targetHost` in Nix,
|
||
and how to define a remote builder for your machine closures.
|
||
|
||
|
||
## Setting `targetHost`
|
||
|
||
Set the machine’s `targetHost` to the reachable IP address of the new machine.
|
||
This eliminates the need to specify `--target-host` in CLI commands.
|
||
|
||
```{.nix title="clan.nix" hl_lines="9"}
|
||
{
|
||
# Ensure this is unique among all clans you want to use.
|
||
meta.name = "my-clan";
|
||
|
||
inventory.machines = {
|
||
# Define machines here.
|
||
# The machine name will be used as the hostname.
|
||
jon = {
|
||
deploy.targetHost = "root@192.168.192.4"; # (1)
|
||
};
|
||
};
|
||
# [...]
|
||
}
|
||
```
|
||
|
||
The use of `root@` in the target address implies SSH access as the `root` user.
|
||
Ensure that the root login is secured and only used when necessary.
|
||
|
||
## Multiple Target Hosts
|
||
|
||
You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](../guides/networking/networking.md).
|
||
|
||
## Updating Machine Configurations
|
||
|
||
Execute the following command to update the specified machine:
|
||
|
||
```bash
|
||
clan machines update jon
|
||
```
|
||
|
||
All machines can be updated simultaneously by omitting the machine name:
|
||
|
||
```bash
|
||
clan machines update
|
||
```
|
||
|
||
---
|
||
|
||
## Advanced Usage
|
||
|
||
The following options are only needed for special cases, such as limited resources, mixed environments, or private flakes.
|
||
|
||
### Setting `buildHost`
|
||
|
||
If the machine does not have enough resources to run the NixOS **evaluation** or **build** itself,
|
||
it is also possible to specify a `buildHost` instead.
|
||
During an update, clan will ssh into the `buildHost` and run `nixos-rebuild` from there.
|
||
|
||
!!! Note
|
||
The `buildHost` option should be set directly within your machine’s Nix configuration, **not** under `inventory.machines`.
|
||
|
||
|
||
```{.nix hl_lines="5" .no-copy}
|
||
clan {
|
||
# ...
|
||
machines = {
|
||
"jon" = {
|
||
clan.core.networking.buildHost = "root@<host_or_ip>";
|
||
};
|
||
};
|
||
};
|
||
```
|
||
|
||
### Overriding configuration with CLI flags
|
||
|
||
`buildHost` / `targetHost`, and other network settings can be temporarily overridden for a single command:
|
||
|
||
For the full list of flags refer to the [Clan CLI](../reference/cli/index.md)
|
||
|
||
```bash
|
||
# Build on a remote host
|
||
clan machines update jon --build-host root@192.168.1.10
|
||
|
||
# Build locally (useful for testing or when the target has limited resources)
|
||
clan machines update jon --build-host local
|
||
```
|
||
|
||
!!! Note
|
||
Make sure the CPU architecture of the `buildHost` matches that of the `targetHost`
|
||
|
||
For example, if deploying to a macOS machine with an ARM64-Darwin architecture, you need a second macOS machine with the same architecture to build it.
|
||
|
||
|
||
### Excluding a machine from `clan machine update`
|
||
|
||
To exclude machines from being updated when running `clan machines update` without any machines specified,
|
||
one can set the `clan.deployment.requireExplicitUpdate` option to true:
|
||
|
||
```{.nix hl_lines="5" .no-copy}
|
||
clan {
|
||
# ...
|
||
machines = {
|
||
"jon" = {
|
||
clan.deployment.requireExplicitUpdate = true;
|
||
};
|
||
};
|
||
};
|
||
```
|
||
|
||
This is useful for machines that are not always online or are not part of the regular update cycle.
|
||
|
||
### Uploading Flake Inputs
|
||
|
||
When updating remote machines, flake inputs are usually fetched by the build host.
|
||
However, if flake inputs require authentication (e.g., private repositories),
|
||
|
||
Use the `--upload-inputs` flag to upload all inputs from your local machine:
|
||
|
||
```bash
|
||
clan machines update jon --upload-inputs
|
||
```
|
||
|
||
This is particularly useful when:
|
||
- The flake references private Git repositories
|
||
- Authentication credentials are only available on local machine
|
||
- The build host doesn't have access to certain network resources
|