hrobot
is an unofficial asynchronous Rust client for interacting with the Hetzner Robot API
See the AsyncRobot
struct for a complete list of supported API Endpoints.
Disclaimer: the authors are not associated with Hetzner (except as customers), and the crate is in no way endorsed or supported by Hetzner Online GmbH.
Requirements for usage
A Hetzner WebService/app user is required to make use of this library.
If you already have a Hetzner account, you can create one through the Hetzner Robot web interface under Settings/Preferences.
Example
Here's a quick example showing how to instantiate the AsyncRobot
client object
and fetching a list of all dedicated servers owned by the account identified by username
use hrobot::*;
#[tokio::main]
async fn main() {
// Robot is instantiated using the environment
// variables HROBOT_USERNAME an HROBOT_PASSWORD.
let robot = AsyncRobot::default();
for server in robot.list_servers().await.unwrap() {
println!("{name}: {product} in {location}",
name = server.name,
product = server.product,
location = server.dc
);
}
}
Running the above example should yield something similar to the output below:
foo: AX51-NVMe in FSN1-DC18
bar: Server Auction in FSN1-DC5
API Endpoint Implementation Progress
The entire Hetzner Robot API is covered at this point!
Some endpoints have not been tested due to the cost and disruption to running servers, so please consult the section below for a detailed overview of the endpoints.
Detailed API overview.
Warning!
1 not tested, use at your own risk.
2 not officially documented by Hetzner, use at own risk.
- Server.
- IP.
- Subnet.
- Reset
- List reset options for all servers.
- Get reset options for single server
- Trigger reset.1
- Failover
- Wake on LAN
- Check availability of Wake-on-LAN.
- Send Wake-on-LAN packet to server.
- Boot Configuration
- Get status of all boot configurations.
- Rescue.
- Get rescue config.
- Get last rescue config.
- Enable rescue config.
- Disable rescue config.
- Linux.
- Get linux config.
- Get last linux config.
- Enable linux config.
- Disable linux config.
- VNC.
- Get VNC config.
- Get last VNC config.2
- Enable VNC config.
- Disable VNC config.
- Windows.1
- Plesk.1
- CPanel.1
- Reverse DNS.
- List reverse DNS entries.
- Get reverse DNS entry
- Create reverse DNS entry.
- Update/create reverse DNS entry.
- Traffic.
- Query traffic data.
- SSH Keys.
- List SSH keys
- Upload new SSH key
- Get SSH key
- Rename SSH key
- Delete SSH key
- Server Ordering.
- Products.
- Market (auction).
- Addons.
- Storage Box.
- List storageboxes.
- Get specific storage box.
- Change storage box password.
- Toggle storage box services.
- Enable/disable Samba
- Enable/disable WebDAV
- Enable/disable SSH
- Enable/disable External reachability
- Enable/disable snapshot directory visibility.
- Snapshots.
- List storagebox snapshots.
- Create storagebox snapshot.
- Delete storagebox snapshot.
- Revert storagebox to snapshot.
- Change comment for snapshot.
- Get storagebox snapshot plan.
- Edit storagebox snapshot plan.
- Subaccounts.
- List subaccounts.
- Create subaccount.
- Update subaccount configuration.
- Delete subaccount.
- Change subaccount password.
- Firewall.
- Get firewall configuration for server.
- Apply firewall configuration to server.
- Override rules.
- Apply template.
- Clear firewall configuration for server.
- Template.
- List firewall templates.
- Create firewall template.
- Get firewall template.
- Update firewall template.
- Delete firewall template.
- vSwitch.
- List vSwitches.
- Create new vSwitch.
- Get vSwitch.
- Update vSwitch.
- Cancel vSwitch.
- Add servers to vSwitch.
- Remove servers from vSwitch.
Testing
Tests are divided into three categories:
-
Isolated tests.
These do not touch the Hetzner API at all and generally test assumptions made in some of the constructs of the library such as serialization/deserialization from known API output. These are always safe to run and do not require Hetzner credentials.
-
Non-disruptive tests.
These interact with the live Hetzner API using credentials provided via the environment variables
HROBOT_USERNAME
andHROBOT_PASSWORD
.The tests fail if these credentials are not available. These tests only perform actions that have no side-effects (such as get/list), and are therefore somewhat safe to execute, but can trigger the rate limiting of the Hetzner API.
These tests are only enabled if the feature
non-disruptive-tests
is enabled. -
Disruptive tests.
These interact with the live Hetzner API using credentials provided via the environment variables
HROBOT_USERNAME
andHROBOT_PASSWORD
.Unlike non-disruptive tests, these tests will interact with and modify existing resources within the provided account, including but not limited to:
- Modifying and deleting the firewall of servers.
- Changing the backup schedule of storageboxes.
- Adding and deleting SSH Keys.
- Ordering and cancelling vSwitches, etc.
Most of these tests are designed to return the resource to its initial state upon completion, but that assumes the test succeeds!
Suffice to say, these tests are incredibly dangerous and should never be run in a production Hetzner account without explicit supervision.
To make sure these are not run accidentally, you have to enable the
disruptive-tests
feature AND and pass the--ignored
flag when runningcargo test
as the tests have been explicitly marked as ignored along with reasoning as to why.