Objects

Object is any infrastructure component you connect to implement commands, such a Linux machine, a network device, etc. Before automating an object, you have to register it with sysopswork. Below is a summary of object characteristics and further down I show the different methods to register an object.

Objects require the following information to be provided:

  • Name

  • Technology

  • IP Address (IPv4 or IPv6)

  • Access Method

  • Login Mode

  • Prompt (optional)

  • Port (optional)

Note: RESTful calls does not require object registration. More details can be found at Automation Script .

Name and Technology

An object is referred by its name, which has the following characteristics:

  • Alphanumeric characters can be used along with the following special characters: “-”, “_” or “.”

  • Whitespaces and tabs are not permitted

  • Has to be in a single line

  • Maximum of 250 characters

In addition to the name, you can also categorize the object to a specific technology. The valid values are:

  • (compute)

  • (network)

  • (security)

  • (storage)

  • (cloud)

  • (container)

Those categories are used right after the object name to distinct different functions of an object with same name.

The technology parameter is optional. If not informed, the default technology is (compute). And this is just a way for sysopswork to distinct objects with the same name (if that is eventually the case).

Examples of valid names are:

  • host001

  • host001.domain.com(compute)

  • router001(network)

When using both name and technology, enclose them within single quotes when running commands on Windows Command Prompt or macOS / Linux Terminal. If you are using only the name (assuming the technology is compute), then there is no need to enclose it within single quotes.

There are 4 objects that are pre-registered by sysopswork by default:

  • AWS

  • Azure

  • GCP

  • localhost

Therefore those names are reserved, meaning that you must not try to register them again.

Address

An object also requires an address. That could be IPv4 or IPv6, depending on how you connect to the object. The address has to be the same one used to connect directly from your computer. If you are connected to an internal network, you should probably use the private IP address of the host. Objects (compute instances) on public cloud are usually accessible by their public IP addresses.

Access Method

There are two methods to access an object to implement commands: SSH and PowerShell Remoting.

The default method is “ssh”.

Note: Object “localhost” does not have access method. Objects “AWS”, “Azure” and “GCP” have their own access methods. More details can be found at Cloud Providers.

SSH

sysopswork assumes the object you are connecting to is legit, and if prompted to confirm, it will do so. Basically, sysopswork will enter yes and continue when it connects to the object through SSH for the first time and has to confirm its key fingerprint:

ECDSA key fingerprint is SHA256:(<a large string>).
Are you sure you want to continue connecting (yes/no)?

PowerShell Remoting

PowerShell Remoting is natively supported among Microsoft products (from a Windows Client to a Windows Server, for instance). From Linux or MacOS client, due to the lack of full support of PowerShell using SSH as transport, enable SSH Server on the remote Windows machine, connect to it using access method “ssh”, then use the command powershell to run remote PowerShell commands.

sysopswork establishes a persistent session with servers on Windows machines configured to accept PowerShell Remoting communication, therefore your automation script must contain PowerShell commands you would use locally at that remote machine.

sysopswork uses most of the default parameters of PowerShell Remoting, including the method of authentication defined by the underlying protocol (WS-MAN).

SSL is not used by default by PowerShell Remoting. If you are using a Windows client, and want to enable SSL, adjust the port number of the object to 443 or 5986 (by default the port used is 5985). Target server must be properly configured to receive SSL connections.

Login Mode

Login mode informs the type of authentication required to access the object. It depends if you are connecting using SSH or PowerShell Remoting.

Note: Object “localhost” does not have login mode. Objects “AWS”, “Azure” and “GCP” have their own login modes. More details can be found at Cloud Providers

SSH Login Modes

Valid login modes for SSH are: “user-pass”, “key”, and “trusted-key”.

The default mode is “user-pass”. For the lack of obviousness, “user” stands for “username”, and “pass” for “password”.

Login mode “key” is used when you have a private key file to authenticate to an object. When persisting credentials for this object, you have to provide the username and the full path of where the PEM key file is located in your machine.

Login mode “trusted-key” is used when client and server exchanged keys and server authorizes connections from respective client. Username still has to be provided, and if the authorized key has a passphrase, you must also provide that information. If the key pair has been generated without a passphrase, then you can leave that information blank when persisting credentials. To simplify, authorized key assumes the default “id_rsa”.

PowerShell Remoting Login Modes

Valid login modes for PowerShell Remoting from a Windows machine are: “user-pass”, “certificate”, and “ca-certificate”. If you are running sysopswork from a macOS or Linux machine, the only valid PowerShell Remoting login mode is “user-pass”.

Same as for SSH, the default mode is “user-pass”. For credentials with domain, enter the username information as DOMAIN\USERNAME.

To use a self-signed certificate instead, use login mode “certificate”, and when persisting credentials enter the certificate thumbprint.

If the certificate is signed by a CA (Certificate Authority), use login mode “ca-certificate”. It requires the certificate thumbprint to persist credentials.

The use of certificate automatically enables SSL, so you don’t have to adjust the port number to 5986 when using login mode “certificate” or “ca-certificate”, unless you are using a custom port (like 443).

Object Prompt (Optional)

Object prompt refers to the constant characters that are provided by the terminal/Command Prompt whenever is ready for a command. For example, an object prompt might look like the following in a terminal/Command Prompt:

user@host001$

And users enter commands after the “$” sign. The part user@host001 is constant in every terminal/Command Prompt line, and it is the prompt of the respective object. This parameter is optional, and we recommend no to set the object prompt unless sysopswork does not identify it (extraordinary cases).

Network Port (Optional)

Port refers to the TCP port used to establish a connection to the object. Only adjust this parameter if the object is listening in a non-default TCP port. If different than default port, valid values are between 1024 and 65535.

Registering An Object

Objects can be registered through 3 different methods:

  • Command Line

  • Script Instruction ADDOBJ:

  • Adjusting objects.csv File

Regardless of the method used, sysopswork uses the file objects.csv for information about objects (with exception of credentials).

Command Line Registration

Open the Command Prompt (on Windows) or Terminal (on macOS or Linux), navigate to sysopswork main directory and:

1. Run the following command from Windows Command Prompt:

sysopswork -o 'NAME(TECHNOLOGY)'

Or from macOS/Linux Terminal:

./sysopswork -o 'NAME(TECHNOLOGY)'
Note: replace NAME by the actual object name, and it does not need to be all uppercase. (TECHNOLOGY) is optional if the technology is (compute).
2. Enter the IP address of the object. It has to be the one you can reach directly from your computer.

3. Enter access method of the object. Details found at section “Access Method” of this page.

4. Enter login mode of the object. Details found at section “Login Mode” of this page.

5. If necessary, enter object prompt. Details found at section “Object Prompt (Optional)” of this page.

6. If necessary, enter network port. Details found at section “Network Port (Optional)” of this page.

sysopswork will automatically create the entry at the object list.

Registering with Script Instruction ADDOBJ:

You can also register an object from within the script, during automation processing. This method is ideal for implementations where new objects are created from a script, especially if an object parameter is unknown until during some step of the implementation. For example, if during the implementation you get the IP address that will be used for a new object, you can use ADDOBJ: after you collect the IP information.

ADDOBJ: uses JSON format. The syntax is:

ADDOBJ: {"name": "OBJECT_NAME", "ip_address": "IP_ADDRESS", "access_method": "ACCESS_METHOD", "login_mode": "LOGIN_MODE", "prompt": "PROMPT", "public_port": "PUBLIC_PORT", "service": "TECHNOLOGY"}

Important: ensure that ADDOBJ: instruction does not contain an object already registered, otherwise the automation will purposely fail at runtime.

Note: ADDOBJ: instruction can also contain credential information. Please, read section “Master Key & Credentials” further down on this page for more details.

Notice that the parameters “name”, “ip_address”, etc. are the same as used on objects.csv files.

The values “OBJECT_NAME”, “IP_ADDRESS”, “ACCESS_METHOD”, “LOGIN_MODE”, “PROMPT”, “PUBLIC_PORT”, and “TECHNOLOGY” have to be replaced by the respective real values.

Only values for “name”, and “ip_address” are required. If the other values are not informed, they assumed their default values, as explained on previous sections of this page.

Registration by Adjusting objects.csv File

Adjusting the objects.csv file (within same directory as sysopswork program) is another way to register objects.

This method is useful for registering multiple objects.

If you use Microsoft Excel or other spreadsheet program to edit objects.csv file, please ensure they continue to save the file as CSV format.

Updating or Deleting an Object Registration

To update or delete an object entry, adjust objects.csv file (within same directory as sysopswork program) for the respective object. We strongly recommend creating a copy of the file before adjusting it.

Master Key & Credentials

The Master Key is the one password used to lock and unlock credentials.

You can either create or change the Master Key. When you change your Master Key, you don’t need to persist object credentials that you already did with the previous Master Key. They will be automatically updated as part of the process, so you can unlock them with the new Master Key.

Creating Master Key

Open the Command Prompt (on Windows) or Terminal (on macOS or Linux), navigate to sysopswork main directory, and run the following command from Windows Command Prompt:

sysopswork -K

Or from macOS/Linux Terminal:

./sysopswork -K

Note: the option used is uppercase K.

Once you have a Master Key, you don’t need to create it again.

It is recommended to change the Master Key every 15 days or sooner.

Changing Master Key

Open the Command Prompt (on Windows) or Terminal (on macOS or Linux), navigate to sysopswork main directory, and run the following command from Windows Command Prompt:

sysopswork -k

Or from macOS/Linux Terminal:

./sysopswork -k

Note: the option used is lowercase k.

Persisting Credentials

To access objects as part of the automation, they require some sort of authentication, and for sysopswork to enter the credentials to implement the instructions provided, those credentials are persisted locally. The credentials are strongly encrypted and can only be decrypted by using your Master Key mentioned previously.

There are 2 methods to persist credentials: on command line or by using ADDOBJ: instruction within your automation script.

Note: you can only persist credentials for objects already registered. In the case of using ADDOBJ: instruction, it does both object registration and credentials persistency in a single action.

To persist credentials of an object using command line method:

Open the Command Prompt (on Windows) or Terminal (on macOS or Linux), navigate to sysopswork main directory, and run the following command from Windows Command Prompt:

sysopswork -c 'NAME(TECHNOLOGY)'

Or from macOS/Linux Terminal:

./sysopswork -c 'NAME(TECHNOLOGY)'

Replace NAME and TECHNOLOGY by respective object values. (TECHNOLOGY) is optional if the technology is (compute).

To persist credentials of an object using ADDOBJ: instruction:

There might be situations where you want your script to automate an object that has not been registered yet nor had the credentials persisted, but sysopswork requires that information in order to automate such object. This is what we called “Dynamic Object”. You have automation instructions for it, but the object itself is created as part of your script. An example is the automation of creating a virtual machine with your cloud provider, then as part of the same script, apply commands to this new VM.

The solution to this situation is by using ADDOBJ: instruction.

The instruction is the same as explained before on section “Registering An Object”, but you include as well the respective credentials information of that object. For example, to register an object with login mode being “key”, the username being “ubuntu” and the key located at “/home/user/key.pem”, the ADDOBJ: instruction would like the following:

ADDOBJ: {"name": "host001", "ip_address": "1.1.1.1", "login_mode": "key", "username": "ubuntu", "keyfilepath": "/home/user/key.pem"}

After this entry you can have instructions to implement commands to this object as part of the same script.

Be careful when sharing your scripts if you have credentials on ADDOBJ: instructions. In such situation, you must remove the sensitive information and request the other user to input her/his own.

The credentials provided on ADDOBJ: instruction depends on the login mode of the object being registered, as per below:

Login Mode

Key-Values

user-pass

“username”: “”, “password”: “”

key

“username”: “”, “keyfilepath”: “”

trusted-key

“username”: “”, “passphrase”: “”

certificate

“thumbprint”: “”

ca-certificate

“thumbprint”: “”

Updating Credentials

Persisted credentials can only by updated through command line. It’s the same procedure as when persisting credentials for the first time.

To update credentials of an object, open the Command Prompt (on Windows) or Terminal (on macOS or Linux), navigate to sysopswork main directory, and run the following command from Windows Command Prompt:

sysopswork -c 'NAME(TECHNOLOGY)'

Or from macOS/Linux Terminal:

./sysopswork -c 'NAME(TECHNOLOGY)'

Replace NAME and TECHNOLOGY by respective object values. (TECHNOLOGY) is optional if the technology is (compute).

Testing Connectivity

It’s best practice to test connectivity to objects, including login, before running your automation scripts.