From 57315737af56b63d14b34171cf2169dabf84dbe0 Mon Sep 17 00:00:00 2001 From: Kirill Eremin <68240227+qireal@users.noreply.github.com> Date: Fri, 5 Dec 2025 10:53:29 +0200 Subject: [PATCH 1/4] Create getting_started.md --- docs/getting_started.md | 109 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 docs/getting_started.md diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..70a321a --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,109 @@ +The Servers.com CLI tool or srvctl is a Command Line Interface to manage Servers.com services. + +## Key terms + +A **resource** is an object to be managed from CLI. It can be a service, product or another entity that you can manage. For example, a dedicated server. + +A **command** is an operation to be performed on a resource or another action initiated from the CLI agent. For example, a command to create a dedicated server. + +An **option** (or **flag**) is an additional argument to a command that makes its action more specific. For example, a flag to perform a command forcibly `-f`. A flag is just a standalone argument `-f`, an option implies adding some additional data to a flag `--label='env:production'`. + +A **configuration** is a file containing a set of parameters. + +A **context** is an environment of a specific configuration. A default context is the one you log in when a name of a specific context is not specified. Access to a context is verified by a Public API token. + +A context has the following limitations: + +- a context name can contain lower and upper case Latin letters, numbers, underscores, periods, dots, minus symbols; +- there can be only one default context; +- if a default context is not specified, the first one from a list will be used. + +## Installation + +The below instructions will guide you through the steps on how to install a Servers.com CLI agent. + +### MacOS + +1) Tap into the Servers.com repository: +``` +brew tap serverscom/serverscom +``` + +2) Install the client: +``` +brew install srvctl +``` + +### Linux + +1) Download an archive from https://github.com/serverscom/srvctl/releases. An operating system and its architecture are specified in the name of an archive. For example, srvctl_0.1.0_linux_amd64.zip is an archive for Linux with the AMD architecture. + +Then, open terminal and perform the below commands. + +2) Extract the archive content: +``` +unzip +``` + +3) Make the **srvctl** file executable: +``` +chmod +x srvctl +``` + +4) Run the **srvctl** file to start using the agent: +``` +./srvctl +``` + +For now, using of the CLI agent is possible when specifying a path to the srvctl file. + +5) To use the CLI agent without directory mentioning, it's necessary to add a location of the srvctl executable file to **.bashrc**. Open the file in a text editor and add this line in the very end of the file: +``` +export PATH=:$PATH +``` + +If srvctl is located in the `/home/user/srvctl_folder/`, the command will look like: `export PATH=/home/user/srvctl_folder/srvctl:$PATH` + +6) Save the file and close it. To apply changes in the current session, perform: +``` +source ~/.bashrc +``` + +### Windows + +1) Download an archive from https://github.com/serverscom/srvctl/releases. An operating system and its architecture are specified in the name of an archive. For example, `srvctl_0.1.0_windows_amd64.zip` is an archive for Windows with the AMD architecture. + +2) Extract the archive. + +3) Run the **srvctl** executable file. + +## Getting started + +Once you have a Servers.com Public API token and has installed the CLI agent, you need to create a context. + +1) Install the Servers.com CLI agent as instructed in the Installation section. + +2) Get a Public API token from the Servers.com [Customer Portal](https://portal.servers.com/iam/api-tokens). + +3) Open terminal and perform commands that are described below. + +4) Log in to the context: +``` +srvctl login +``` + +There are no contexts yet; so, this operation will create a context and give it a name that you entered within this command. + +5) Enter your Public API token and confirm. + +The newly created context will be setup as default. + +6) When a context is successfully created, it will be shown by the listing contexts command: +``` +srvctl context list +``` + +7) Use the help command to explore other possibilities of the agent: +``` +srvctl help +``` From 59468074468f42581dd3b8b72a6018cc6700c250 Mon Sep 17 00:00:00 2001 From: Kirill Eremin <68240227+qireal@users.noreply.github.com> Date: Fri, 5 Dec 2025 10:58:16 +0200 Subject: [PATCH 2/4] Create hosts.md --- docs/hosts.md | 390 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 390 insertions(+) create mode 100644 docs/hosts.md diff --git a/docs/hosts.md b/docs/hosts.md new file mode 100644 index 0000000..c25bed9 --- /dev/null +++ b/docs/hosts.md @@ -0,0 +1,390 @@ +## hosts + +A host is a bare metal-based service that includes dedicated servers, Kubernetes bare metal nodes and scalable bare metal. This section describes all host-related commands. +### Usage +``` +srvctl hosts [command] [flags] +``` +### Commands + +`ds` - opens a list of commands to manage dedicated servers. +``` +srvctl hosts ds +``` + +`kbm` - opens a list of commands to manage Kubernetes Bare Metal nodes. +``` +srvctl hosts kbm +``` + +`list` - lists all hosts. +``` +srvctl hosts list +``` + +`sbm` - opens a list of commands to manage Scalable Bare Metal. +``` +srvctl hosts sbm +``` +### Flags + +- `-f`, `--field` - a string that selects a field to show. To display several fields, use this flag multiple times. + +- `--field-list` - a list of available fields. + +- `--page-view` - enables the page view format. + +- `-t`, `--template` - a Go template string for advanced customization. Example: `--template "{{range .}}CustomTitle: {{.Title}}\n{{ end }}"` + +- Global flags +### Examples + +A command to list all account hosts showing their ID, Title and Status: +``` +srvctl hosts list -f ID -f Title -f Status --all +``` +## hosts ds + +A set of commands to manage dedicated servers. +### Usage +``` +srvctl hosts ds [command] [flags] +``` +### Commands + +`abort-release` - cancels a scheduled release. +``` +srvctl hosts ds abort-release ex4mp1eID +``` + +`add` - creates a dedicated server (see the **hosts ds add** section). + +`add-network` - adds a network to the selected server. +``` +srvctl hosts ds add-network ex4mp1eID --distribution-method route --mask 32 --type private +``` + +`add-ptr` - adds a PTR record to the selected server. +``` +srvctl hosts ds add-ptr ex4mp1eID --domain example.com --ip X.X.X.X --priority 1 --ttl 360 +``` + +`delete-network` - deletes a specified network for the selected server. +``` +srvctl hosts ds delete-network ex4mp1eID_server --network-id ex4mp1eID_network +``` + +`delete-ptr` - deletes a specified PTR record for the selected server. +``` +srvctl hosts ds delete-ptr ex4mp1eID_server --ptr-id ex4mp1eID_ptr +``` + +`get` - provides information for the selected server. +``` +srvctl hosts ds get ex4mp1eID +``` + +`get-network` - provides information about a specified network of the selected server. +``` +srvctl hosts ds get-network ex4mp1eID_server --network-id ex4mp1eID_network +``` + +`get-oob-credentials` - provides OOB credentials for the selected server. A GPG key fingerprint is needed. +``` +srvctl hosts ds get-network ex4mp1eID_server --fingerprint GPGKEYEX4MP1E +``` + +`ls`, `list` - lists dedicated servers of the account. Use `–help` to see available flags. +``` +srvctl hosts ds list ex4mp1eID --all +``` + +`list-connections` - lists connections for the selected dedicated server. Use `–help` to see available flags. +``` +srvctl hosts ds list-connections ex4mp1eID +``` + +`list-drive-slots` - lists drive slots for the selected dedicated server. Use `–help` to see available flags. +``` +srvctl hosts ds list-drive-slots ex4mp1eID +``` + +`list-features` - lists features for the selected dedicated server. Use `–help` to see available flags. +``` +srvctl hosts ds list-features ex4mp1eID +``` + +`list-networks` - lists networks for the selected dedicated server. Use `–help` to see available flags. +``` +srvctl hosts ds list-networks ex4mp1eID +``` + +`list-power-feeds` - lists power feeds for the selected dedicated server. +``` +srvctl hosts ds list-power-feeds ex4mp1eID +``` + +`list-ptr` - lists PTR records for the selected dedicated server. Use `–help` to see available flags. +``` +srvctl hosts ds list-ptr ex4mp1eID +``` + +`list-services` - lists services for the selected dedicated server. +``` +srvctl hosts ds list-ptr ex4mp1eID +``` + +`power` - sends a specified power command for the selected dedicated server (see the **hosts ds power** section). + +`reinstall` - reinstalls an operating system for the selected dedicated server (see the **hosts ds reinstall** section). + +`schedule-release` - schedules release on YYYY-MM-DDTHH:MM:SS+HH:MM (dateTtime+time zone from UTC) for the selected dedicated server. +``` +srvctl hosts ds schedule-release ex4mp1eID --release-after 2022-05-24T12:48:00+03:00 +``` + +`update` - updates parameters for the selected dedicated server. +``` +srvctl hosts ds update ex4mp1eID --label environment=production --label team=frontend +``` +### Flags + +Global flags +## hosts ds add + +A command to create a dedicated server. It allows to pass parameters of the server in two ways: + +- Input - server parameters are described in a file, a path to the file is specified via the `-i` or `–input` flag. The path can be absolute or relative to the srvctl file. + +- Flags - parameters are specified via flags inside the command and hostnames are listed as position arguments. As many arguments, as many servers of this configuration will be created. +### Usage +``` +srvctl hosts ds add -i [path] +srvctl hosts ds add [flags] [hostname1] [hostnameN] +``` +### Flags + +- `--location-id` - a unique identifier of a location. Use `srvctl locations list` to list all location IDs. + +- `--server-model-id` - a unique identifier of a server model. Use `srvctl server-models list --location-id ` to list all server models. + +- `--ram-size` - an integer value of RAM in GB. + +- `--operating-system-id` - a unique identifier of an operating system. Use `srvctl server-os-options list --location-id --server-model-id ` to list all OS IDs. + +- `--public-uplink-id` - a unique identifier of a public uplink. Use `srvctl uplink-models list --location-id --server-model-id ` to list all public uplinks. + +- `--public-bandwidth-id` - a unique identifier of a public uplink bandwidth. Use `srvctl uplink-bandwidths list --location-id --server-model-id --uplink-model-id ` to list all bandwidth IDs. + +- `--private-uplink-id` - a unique identifier of a private uplink. Use `srvctl uplink-models list --location-id --server-model-id ` to list all private uplinks. + +- `--drive-slots` - a parameter to specify a disk model ID for a slot. Slots start from 0. This is the flag pattern for two disk slots: `--drive-slots = --drive-slots =`. Use `srvctl drive-models list --location-id --server-model-id ` to list disk model IDs. + +- `--layout` - a RAID level for disks in slots. An example of pattern for two disks: `--layout=slot=,slot=,raid=`. An example for RAID 1: `--layout=slot=0,slot=1,raid=1`. + +- `--partition` - partition parameters (target, fs, fill, size) for a disk in the specified slot. If two disks are within one RAID, both of them should be listed. This is an example for a boot partition and RAID1 of two disks: `--partition=slot=0,slot=1,target=/boot,fs=ext4,size=1024,fill=false` + +- `--feature` - a string with features that has to be named as per [Public API](https://developers.servers.com/api-documentation/v1/#tag/Location/operation/ListLocations). For example, `--feature no_private_ip` + +- `--ipv6` - a flag to add a public IPv6 address. It's necessary to specify this option `--ipv6` without additional values to activate the feature: the presence of the flag itself implies IPv6 enabling. + +- `--labels` - a flag to assign labels to a server. For example: `--labels environment=production` + +- `--user-data` - a flag that processes user data from a string: `--user-data ` + +- `--user-data-file` - a flag that collects user data from a specified directory. An example for a file located in the same directory with srvctl: `--user-data-file example.txt` + +- `-i`, `--input` - a flag to specify a file with order parameters (see **Create server via input**). +### Examples +#### Create server via input + +The `-i`, `--input` allows to provide parameters of a created server in a local file. Parameters should be described as a request body of the [Public API request](https://developers.servers.com/api-documentation/v1/#tag/Dedicated-Server/operation/CreateADedicatedServer). + +An example of a command for a file in the same directory with srvctl: +``` +srvctl hosts ds add --input +``` + +An example of the file's content: +``` +{ + "server_model_id": 10515, + "location_id": 2, + "ram_size": 32, + "uplink_models": { + "public": { + "id": 10198, + "bandwidth_model_id": 13744 + }, + "private": { + "id": 10201 + } + }, + "drives": { + "slots": [ + { + "position": 0, + "drive_model_id": 10306 + }, + { + "position": 1, + "drive_model_id": 10306 + } + ], + "layout": [ + { + "slot_positions": [ + 0, + 1 + ], + "raid": 1, + "partitions": [ + { + "target": "/", + "size": 10240, + "fill": false, + "fs": "ext4" + }, + { + "target": "/boot", + "size": 1024, + "fill": false, + "fs": "ext4" + }, + { + "target": "/home", + "size": 1, + "fill": true, + "fs": "ext4" + } + ] + } + ] + }, + "ipv6": false, + "hosts": [ + { + "hostname": "" + } + ], + "operating_system_id": 62, + "ssh_key_fingerprints": [ + "" + ] +} +``` + +There is also an option to use standard input (stdin) when specifying the flag this way: `--input -` +#### Create server via flags + +It's possible to pass server parameters via flags that are described in the **Flags** section. This is an example of a command to create a dedicated server: +``` +srvctl hosts ds add \ + --location-id 2 \ + --server-model-id 10515 \ + --ram-size 32 \ + --operating-system-id 62 \ + --public-uplink-id 10198 \ + --public-bandwidth-id 13744 \ + --private-uplink-id 10201 \ + --drive-slots 1=10306 \ + --drive-slots 2=10306 \ + --layout=slot=0,slot=1,raid=1 \ + --partition=slot=0,slot=1,target=/,fs=ext4,size=10240,fill=false \ + --partition=slot=0,slot=1,target=/boot,fs=ext4,size=1024,fill=false \ + --partition=slot=0,slot=1,target=/home,fs=ext4,size=1,fill=true \ + --feature no_private_ip \ + --ipv6 \ + +``` + + The only available authentication method is password. An SSH key can be added only via the input process (see **Create server via input**) +## hosts ds power + +A command to manage power operations on a server. +### Usage +``` +srvctl hosts ds power [flags] +``` +### Flags + +- `--command off` - a flag to power off a server. + +- `--command on` - a flag to power on a server. + +- `--command cycle` - a flag for the power cycle command. +### Examples + +An example of a command to switch a server off: +``` +srvctl hosts ds power --command off +``` +## hosts ds reinstall + +A command to reinstall an operating system on a dedicated server. +### Usage +``` +srvctl hosts ds reinstall [flags] +``` +### Flags + +- `-i`, `--input` - a flag to specify a path with a file that contains reinstall parameters. +### Examples + +The `-i`, `--input` allows to provide parameters of a created server in a local file. Parameters should be described as a request body of the [Public API request](https://developers.servers.com/api-documentation/v1/#tag/Dedicated-Server/operation/CreateADedicatedServer). + +An example of a command for a file in the same directory with srvctl: +``` +srvctl hosts ds reinstall --input +``` + +An example of the file's content: +``` +{ + "hostname": "", + "drives": { + "slots": [ + { + "position": 0, + "drive_model_id": 10306 + }, + { + "position": 1, + "drive_model_id": 10306 + } + ], + "layout": [ + { + "slot_positions": [ + 0, + 1 + ], + "raid": 1, + "partitions": [ + { + "target": "/", + "size": 10240, + "fill": false, + "fs": "ext4" + }, + { + "target": "/boot", + "size": 1024, + "fill": false, + "fs": "ext4" + }, + { + "target": "/home", + "size": 1, + "fill": true, + "fs": "ext4" + } + ] + } + ] + }, + "operating_system_id": 49 +} +``` + +There is also an option to use standard input (stdin) when specifying the flag this way: `--input -` From 0a09b312396d924e18f126c6991a4f4db37b3ab9 Mon Sep 17 00:00:00 2001 From: Kirill Eremin <68240227+qireal@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:12:40 +0200 Subject: [PATCH 3/4] Update hosts.md --- docs/hosts.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/hosts.md b/docs/hosts.md index c25bed9..ca807af 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -35,8 +35,6 @@ srvctl hosts sbm - `--page-view` - enables the page view format. - `-t`, `--template` - a Go template string for advanced customization. Example: `--template "{{range .}}CustomTitle: {{.Title}}\n{{ end }}"` - -- Global flags ### Examples A command to list all account hosts showing their ID, Title and Status: @@ -94,9 +92,9 @@ srvctl hosts ds get-network ex4mp1eID_server --network-id ex4mp1eID_network srvctl hosts ds get-network ex4mp1eID_server --fingerprint GPGKEYEX4MP1E ``` -`ls`, `list` - lists dedicated servers of the account. Use `–help` to see available flags. +`list` - lists dedicated servers of the account. Use `–help` to see available flags. ``` -srvctl hosts ds list ex4mp1eID --all +srvctl hosts ds list --all ``` `list-connections` - lists connections for the selected dedicated server. Use `–help` to see available flags. @@ -147,9 +145,6 @@ srvctl hosts ds schedule-release ex4mp1eID --release-after 2022-05-24T12:48:00+0 ``` srvctl hosts ds update ex4mp1eID --label environment=production --label team=frontend ``` -### Flags - -Global flags ## hosts ds add A command to create a dedicated server. It allows to pass parameters of the server in two ways: From 6f687d2d9f8e1ff3768314c1e746ae5547b63dcc Mon Sep 17 00:00:00 2001 From: Kirill Eremin <68240227+qireal@users.noreply.github.com> Date: Tue, 9 Dec 2025 11:14:28 +0200 Subject: [PATCH 4/4] Update hosts.md --- docs/hosts.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/hosts.md b/docs/hosts.md index ca807af..3c35334 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -1,11 +1,11 @@ ## hosts A host is a bare metal-based service that includes dedicated servers, Kubernetes bare metal nodes and scalable bare metal. This section describes all host-related commands. -### Usage +#### Usage ``` srvctl hosts [command] [flags] ``` -### Commands +#### Commands `ds` - opens a list of commands to manage dedicated servers. ``` @@ -26,7 +26,7 @@ srvctl hosts list ``` srvctl hosts sbm ``` -### Flags +#### Flags - `-f`, `--field` - a string that selects a field to show. To display several fields, use this flag multiple times. @@ -35,7 +35,7 @@ srvctl hosts sbm - `--page-view` - enables the page view format. - `-t`, `--template` - a Go template string for advanced customization. Example: `--template "{{range .}}CustomTitle: {{.Title}}\n{{ end }}"` -### Examples +#### Examples A command to list all account hosts showing their ID, Title and Status: ``` @@ -44,11 +44,11 @@ srvctl hosts list -f ID -f Title -f Status --all ## hosts ds A set of commands to manage dedicated servers. -### Usage +#### Usage ``` srvctl hosts ds [command] [flags] ``` -### Commands +#### Commands `abort-release` - cancels a scheduled release. ``` @@ -152,12 +152,12 @@ A command to create a dedicated server. It allows to pass parameters of the serv - Input - server parameters are described in a file, a path to the file is specified via the `-i` or `–input` flag. The path can be absolute or relative to the srvctl file. - Flags - parameters are specified via flags inside the command and hostnames are listed as position arguments. As many arguments, as many servers of this configuration will be created. -### Usage +#### Usage ``` srvctl hosts ds add -i [path] srvctl hosts ds add [flags] [hostname1] [hostnameN] ``` -### Flags +#### Flags - `--location-id` - a unique identifier of a location. Use `srvctl locations list` to list all location IDs. @@ -190,8 +190,8 @@ srvctl hosts ds add [flags] [hostname1] [hostnameN] - `--user-data-file` - a flag that collects user data from a specified directory. An example for a file located in the same directory with srvctl: `--user-data-file example.txt` - `-i`, `--input` - a flag to specify a file with order parameters (see **Create server via input**). -### Examples -#### Create server via input +#### Examples +##### Create server via input The `-i`, `--input` allows to provide parameters of a created server in a local file. Parameters should be described as a request body of the [Public API request](https://developers.servers.com/api-documentation/v1/#tag/Dedicated-Server/operation/CreateADedicatedServer). @@ -270,7 +270,7 @@ An example of the file's content: ``` There is also an option to use standard input (stdin) when specifying the flag this way: `--input -` -#### Create server via flags +##### Create server via flags It's possible to pass server parameters via flags that are described in the **Flags** section. This is an example of a command to create a dedicated server: ``` @@ -297,18 +297,18 @@ srvctl hosts ds add \ ## hosts ds power A command to manage power operations on a server. -### Usage +#### Usage ``` srvctl hosts ds power [flags] ``` -### Flags +#### Flags - `--command off` - a flag to power off a server. - `--command on` - a flag to power on a server. - `--command cycle` - a flag for the power cycle command. -### Examples +#### Examples An example of a command to switch a server off: ``` @@ -317,14 +317,14 @@ srvctl hosts ds power --command off ## hosts ds reinstall A command to reinstall an operating system on a dedicated server. -### Usage +#### Usage ``` srvctl hosts ds reinstall [flags] ``` -### Flags +#### Flags - `-i`, `--input` - a flag to specify a path with a file that contains reinstall parameters. -### Examples +#### Examples The `-i`, `--input` allows to provide parameters of a created server in a local file. Parameters should be described as a request body of the [Public API request](https://developers.servers.com/api-documentation/v1/#tag/Dedicated-Server/operation/CreateADedicatedServer).