Resource Onboarding Guide

The basic OpsAny workflow is: enter resources → onboard resources → manage resources. Once your resources are catalogued and entered, you onboard them (bring them under OpsAny's management). This manual covers using the 【Control Platform】 for onboarding, plus common problems. OpsAny follows a three-tier Server-Proxy-Agent architecture; a default installation deploys one built-in Proxy automatically.

How OpsAny Proxy onboarding works

Proxy network connectivity

OpsAny supports multiple controllers (Proxies). Each controller manages the hosts, network devices, and databases in its own region, and all Proxies connect to OpsAny.

Ports the Proxy listens on:

• 4505, 4506: Agent-mode service ports
• 8010: Proxy service process port
• 8011: OpenResty HTTPS port proxying the Proxy
• 8012: OpenResty HTTP port proxying the Proxy

Host onboarding:

• The OpsAny platform must reach port 8011 on the Proxy. Onboarded hosts must reach ports 8011 and 8012 on the Proxy (to download files and scripts).
• SSH mode: the Proxy must reach port 22 on every host (target passive mode).
• Agent mode: every host must reach ports 4505 and 4506 on the Proxy (target active mode).

Other resources:

• Telnet protocol: onboarding network devices may involve connecting over Telnet.
• Database protocols: onboarding databases involves connecting to the target instance over the MySQL, Redis, or MongoDB protocol.

The Proxy also connects to the OpsAny platform to fetch files and scripts users upload. In multi-Proxy mode, if some Proxies sit on the public internet, the OpsAny platform must be publicly reachable.

Host onboarding under a Proxy

OpsAny supports four host onboarding methods:

• Agent: onboard through the Agent.
• SSH: onboard over SSH.
• Agent/SSH: dual channel, Agent first. It checks whether the Agent connects; if so it uses the Agent. If the Agent fails, it uses SSH.
• SSH/Agent: dual channel, SSH first. It checks whether SSH connects; if so it uses SSH. If SSH fails, it uses the Agent.

Authentication methods:

• Password: enter the correct username and password.
• Key: the public key must be in place beforehand. You can generate a key pair in the Workbench, then place the public key on the target host as follows:
  • 1. Create .ssh/authorized_keys in the user's home directory; the .ssh directory needs mode 700 and authorized_keys mode 600
  • 1. Write the public key into "/root/.ssh/authorized_keys" or "/home/regular-user/.ssh/authorized_keys"
  • 1. When signing in with a credential, the username or resource account must be the corresponding username

Request call chain

For example, when a user runs a quick script, distributes files, or executes a job in the Job Platform, the call chain is:

【Job Platform】 → 【ESB】 → 【Control Platform】 → 【Proxy】 → (over SSH or Agent) → 【Host】

When a user runs an asset collection task in the Resource Platform, the call chain is:

【Resource Platform】 → 【ESB】 → 【Control Platform】 → 【Proxy】 → (over SSH or Agent) → 【Host】

When something goes wrong you can troubleshoot hop by hop along the call chain. The Control Platform and the Proxy are the core of every execution.

Onboarding hosts in OpsAny

Linux hosts

Linux hosts support SSH and Agent. SSH supports both regular users and root. Agent supports automatic and manual installation; after a manual installation, click "Onboard" under Actions yourself.

• Using SSH keys for onboarding is strongly recommended. With username/password, you must update the credential in the Control Platform by hand whenever the password changes.

Linux host — SSH password

With SSH password onboarding you work directly in 【Control Platform】 → 【Host Management】.

Just enter the username and password when onboarding. If you use a regular user, configure and enable sudo beforehand.

Linux host — SSH key

1. Sign in to the Proxy host and create an SSH key pair

# Enter the Proxy container
docker exec -it opsany-paas-proxy /bin/bash

# Create the key pair
ssh-keygen -t rsa -b 3072
Generating public/private rsa key pair.
Enter file in which to save the key (/root/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /root/.ssh/id_rsa
Your public key has been saved in /root/.ssh/id_rsa.pub

1. Push the key from the Proxy to the target host

# Push manually
ssh-copy-id root@192.168.56.11

1. Upload the private key under 【Workbench】 → 【Personal Settings】 → 【Key Management】.

2. Select the corresponding private key when configuring 【Control Platform】 → 【Host Management】.

Linux host — Agent

Linux Agent onboarding supports automatic and manual deployment. If automatic deployment fails, choose manual.

• Automatic Agent deployment: the user supplies a username/password or a key. The platform connects to the target host and runs the installation script.
• Manual Agent deployment: the user copies the generated command to the target host and runs it.

Windows hosts

Windows host onboarding supports Agent mode only, and requires manual configuration on the target Windows host beforehand.

Windows host — SSH (not supported)

SSH onboarding of Windows is not supported yet; a later version will add it.

Windows host — Agent

Windows Agent onboarding requires installing the Agent manually on the Windows host. Make sure the onboarded Windows host can reach ports 4505 and 4506 on the Proxy. How: Control Platform → Add Host, choose Windows as the operating system and Agent as the onboarding method. After adding, Actions → More offers a manual onboarding option that shows the command to install the Agent by hand.

If the host you are onboarding is old — for example Windows 2003 — you may need to install an early SaltStack release manually. Downloads: - https://mirrors.tuna.tsinghua.edu.cn/saltstack/windows/archive/ - For Windows Server 2003 we recommend version 2015.8.

Host onboarding troubleshooting

SSH troubleshooting

SSH onboarding and connection tests run through Ansible, so when SSH misbehaves you can test with Ansible directly and inspect the logs.

Common causes:

• The host is unreachable; ping fails.
• The host is reachable and ping works, but the port does not respond.
• The host IP and port are fine, but authentication fails (password or key).
• The host IP and port are fine and the credentials are definitely correct, but the SSH version may not support the algorithm in use. Edit /etc/ssh/ssh_config to enable it.

All of these can be diagnosed with the steps below.

• Adjust SSH parameters to support older SSH, for example CentOS 6

# Enter the Proxy container
docker exec -it opsany-paas-proxy /bin/bash
# Create the file if it does not exist.
vi /etc/ssh/ssh_config
Host *
  HostKeyAlgorithms ssh-rsa,ssh-dss
  PubkeyAcceptedKeyTypes +ssh-rsa,ssh-dss

• Enter the OpsAny Proxy container.

# For Docker
docker exec -it opsany-paas-proxy /bin/bash

# For Kubernetes
kubectl exec -it PodName -n opsany -- /bin/bash

• Run the following commands

# Use Ansible to test connectivity.
ansible -vvv -i /opt/opsany-proxy/invscript_proxy.py node-unique-id -m ping

# Use Ansible to test data collection.
ansible -vvv -i /opt/opsany-proxy/invscript_proxy.py node-unique-id -m setup

Agent troubleshooting

The OpsAny Agent is a self-contained Python environment requiring no dependencies. The host does not need Python installed, and any existing Python environment is unaffected. It installs to /usr/local/opsany-agent by default and that location cannot be changed. Processes are managed by Supervisor and registered as a Service or systemd unit automatically. Only Python 3 is supported. It has no impact on the operating system's existing Python, and the Agent does not leak memory or peg the CPU, so it is safe to install.

About the Agent

1. Where the Agent package lives.

The Agent package is stored in /opt/opsany/uploads/agent on the OpsAny Proxy (controller); that directory is exposed for download through OpenResty.

cd /opt/opsany/conf/nginx-conf.d
cat nginx_paas.conf
...
    location ~ ^/uploads/(.*) {
        autoindex off;
        root /opt/opsany/;
    }
...

If Agent installation fails, check whether you actually put the agent package into the uploads directory. The installation documentation includes that step; you may have skipped it.

1. What the Agent package contains

The Agent is a custom Python package: no installation needed, just extract it, with no dependencies.

Agent onboarding states

Agent onboarding is the method most prone to problems, mainly network configuration. Below are all Agent states; use them to troubleshoot.

• Normal: the Agent connection is healthy and remote commands can run.
• Starting installation: Agent installation begins — make sure the Agent package is in place under uploads beforehand.
• Installing: installation is in progress. The next state is installation succeeded or installation failed.
• Installation succeeded: the installation script succeeded. This state usually is not shown, because onboarding starts immediately.
• Installation failed: the installation script failed, usually for system reasons; reinstall or fix it manually.
• Onboarding: accepting the key the Agent registered. It retries once on failure.
• Onboarding succeeded: the Agent key was accepted. This state usually is not shown, because onboarding proceeds immediately.
• Onboarding failed: accepting the Agent key failed, typically because the host's unique identifier is duplicated.
• Abnormal: everything above succeeded but the Agent connection is unhealthy — usually a firewall blocking the Agent from reaching ports 4505 and 4506 on the Proxy, or network instability.

Managing the OpsAny Agent

1. Check Agent status

systemctl status opsany-agent

1. Stop the Agent

systemctl stop opsany-agent

1. Check plugin status inside the Agent

The Agent manages its plugins with Supervisor; a script wraps supervisorctl for status.

/usr/local/opsany-agent/agent.sh status

1. Restart all Agent services

/usr/local/opsany-agent/agent.sh restart all

1. Uninstall the Agent

/usr/local/opsany-agent/agent.sh remove
rm -rf /usr/local/opsany-agent/

1. How does a manually installed Agent get discovered?

A manually installed Agent registers itself with the Proxy when it starts. Then onboard the host manually under 【Control Platform】 Host Management → Actions (More) → Onboard. Once the status is normal, you can run asset collection.

Agent troubleshooting steps

1. Manage the onboarded host list

List all Agent-onboarded hosts
# docker exec -it opsany-paas-proxy /bin/bash
# salt-key
Accepted Keys: (hosts below this line are onboarded)
Denied Keys: (hosts below this line have connected but are refused)
Unaccepted Keys: (hosts below this line have connected but are not onboarded yet)

Remove a host's onboarding
# salt-key -d node-ID-name

Accept a host's onboarding
# salt-key -i 'linux-node2'

1. Check the status of Agents connected to the Proxy

# docker exec -it opsany-paas-proxy /bin/bash
# salt '*' test.ping (check all Agent states)
# salt 'linux-node1' test.ping  (check a specific Agent)

1. Common causes of Agent onboarding problems

2. 1. The Agent was installed manually but does not appear in salt-key. Check the Agent configuration file — possibly the node ID duplicates another host's, or the Proxy address is wrong.
3. 1. salt-key shows no hosts at all. Check whether you signed in to the wrong Proxy (if you have several).
4. 1. The onboarded host had its operating system reinstalled. The correct action is to remove the onboarding and onboard again, never patch the old host.

Network device onboarding

Network device onboarding in the Control Platform is a Community Edition test feature and is not recommended for production. There are too many vendors and models to be compatible with; in practice, debugging and compatibility work happens during Enterprise Edition implementations.

Database onboarding

OpsAny Community Edition has supported MySQL and Redis onboarding since v1.6.7. Onboarding shows the instance's basic information and enables basic operations in the UI.

Bastion Host onboarding

Bastion Host onboarding is completely separate from Proxy-based onboarding of hosts, network devices, and databases — they are unrelated. For example, the Bastion Host may onboard a host successfully while the controller fails, and vice versa.

• The Bastion Host onboards through the opsany-paas-websocket container.
• The controller onboards through the opsany-paas-proxy container.

When the Bastion Host fails authentication, the most direct test is to try connecting from inside opsany-paas-websocket. Some operating systems cannot connect because of their SSH algorithm support, much like host onboarding.

# Enter the WebSocket container
docker exec -it opsany-paas-websocket /bin/bash

# Test the network and SSH connection manually
ping 192.168.56.11
ssh root@192.168.56.11

Bastion Host authorization

The Bastion Host authorizes through permission policies. Administrators see all resources by default; regular users need authorization through the Bastion Host's access policies, which can grant a user a specific target host, as a specific identity, within a specific time window. Access policies are extremely flexible.

Uploading and downloading files on Linux hosts

On Linux hosts the right-hand file panel shows only the user's home directory. To upload elsewhere or download from elsewhere, move the file into the home directory first (this restriction is deliberate). Note: if the lrzsz package is installed, you can upload and download with rz and sz directly.

Uploading and downloading files on Windows hosts

On Windows hosts a network drive named "Downloads on OpsAny" is created in 【My Computer】. Files uploaded from the right-hand panel appear on that drive. To download a file from the Windows host, copy or move it to that shared drive. Note: early versions had a Download directory on the drive; the current version removed it.

FAQ

Switching from password to key authentication after onboarding

If you already onboarded with a password and now want to switch to a key, do the following:

# docker exec -it opsany-paas-proxy /bin/bash
# ansible -i /opt/opsany-proxy/invscript_proxy.py 192.168.4.108 -m authorized_key -a "user=root state=present key={{ lookup('file', '/root/.ssh/id_rsa.pub') }}"

---