Link Search Menu Expand Document

Command Line Interface (CLI)

FogROS 2 uses Python entry points to extend the commands and verbs for ROS 2’s CLI. Specifically, the fogros2 package adds the fog command with three verbs, list, connect and delete for easy viewing of, interaction with, and termination of remote instances, respectively. More information about commands or verbs can be found by running ros2 fog --help or ros2 fog <verb> --help.

CLI Commands

list

Prints information about existing FogROS 2 instances.

Usage

ros2 fog list [-h] [--region REGION [REGION …]]

Description

Prints a list of details – instance name, cloud service provider (currently always AWS), region, instance type, region, id, IP address, SSH key, disk size, AMI, and state – for existing FogROS 2 instances. With no REGION specified, this command defaults to listing instances in the region set in the user’s AWS configuration or in the corresponding environment variable. Otherwise, it lists all FogROS 2 instances in REGION or in multiple regions if specified.

Options

-h, --help
Print usage, argument, and options information and exit.

--region REGION [REGION …]
Specify the AWS region(s) for listing instances (overrides config or environment variables that are set). Multiple regions can be listed and separated by a space, and the output will include instances from all regions listed.

Examples

If there are two current instances running with names “great-bulkhead” and “associative-singularity”:

$ ros2 fog list 
====== great-bulkhead ======
cloud_service_provider: AWS  
ec2_region: None  
ec2_instance_type: t2.micro  
ec2_instance_id: i-002391eea4a22a6ba  
public_ip: 13.57.237.42  
ssh_key: FogROS2KEY-great-bulkhead  
disk_size: 30  
aws_ami_image: ami-00f25057ddc9b310b  
state: running  
====== associative-singularity ======  
cloud_service_provider: AWS  
ec2_region: None  
ec2_instance_type: t2.micro  
ec2_instance_id: i-071770e8a9f6d18e9  
public_ip: 18.144.35.60  
ssh_key: FogROS2KEY-associative-singularity  
disk_size: 30  
aws_ami_image: ami-00f25057ddc9b310b  
state: running  

One could also receive the same output as above by specifying the region directly:

$ ros2 fog list --region us-west-1

connect

Opens a shell connection to an existing instance.

Usage

ros2 fog connect [-h] [--region [REGION [REGION …]]] [--user [USER]] NAME

Description

Connects via SSH to an existing FogROS 2 instance with name NAME, allowing the user to run commands from a shell directly on the instance. FogROS 2 instance names can be found using the list command. If no instances with name NAME are found in the specified region, this command will print “No matching instance found” and exit.

Options

-h, --help
Print usage, argument, and options information and exit.

--region REGION [REGION …]
Match only instances with name NAME in the AWS region(s) REGION (overrides config or environment variables that are set). Multiple regions can be listed and separated by a space, and all regions will be searched for an instance with name NAME.

-u USER, --user USER
Connect as user USER to the remote SSH instance. If this option is not specified, the default user is “ubuntu”.

Examples

To connect to a currently running instance called “great-bulkhead”:

$ ros2 fog connect great-bulkhead
Welcome to Ubuntu 20.04.3 LTS (GNU/Linux 5.11.0-1022-aws x86_64)

 * Documentation:  https://help.ubuntu.com  
 * Management:     https://landscape.canonical.com  
 * Support:        https://ubuntu.com/advantage  

 System information disabled due to load higher than 1.0


231 updates can be applied immediately.  
163 of these updates are standard security updates.  
To see these additional updates run: apt list --upgradable  


Last login: Thu Feb 24 19:38:54 2022 from 128.32.37.69  
ubuntu@ip-172-31-7-52:~$

Note: Output is given as an example, but likely will be different from above.
Note: A notice saying that the authenticity of the host can’t be established may be shown; you will need to confirm that you wish to continue to connect in this case.

delete

Terminates a running instance.

Usage

ros2 fog delete [-h] [--region [REGION [REGION …]]] [--dry-run] NAME

Description

Terminates an existing FogROS 2 instance with name NAME and removes the key pair and data folder associated with the instance. If NAME is all, then all FogROS 2 instances in the specified regions will be terminated. FogROS 2 instance names can be found using the list command. If no instances with name NAME are found in the specified region, this command will print “No EC2 instances found with the specified name; check list to be sure name is correct! No instances deleted” and exit.

Options

--dry-run
Show which instances and keys would be terminated and deleted without actually executing the commands to do so.

-h, --help
Print usage, argument, and options information and exit.

--region REGION [REGION …]
Match only instances with name NAME in the AWS region(s) REGION (overrides config or environment variables that are set). Multiple regions can be listed and separated by a space, and all regions will be searched for an instance with name NAME.

Examples

The following examples assume there are two instances running with names “great-bulkhead” and “associative-singularity”.

To terminate both running instances:

$ ros2 fog delete all
Deleting great-bulkhead i-002391eea4a22a6ba  
    terminating instance i-002391eea4a22a6ba  
    deleting key pair FogROS2KEY-great-bulkhead  
    done.  
Deleting associative-singularity i-071770e8a9f6d18e9  
    terminating instance i-071770e8a9f6d18e9  
    deleting key pair FogROS2KEY-associative-singularity  
    done.  

To terminate just “great-bulkhead”:

$ ros2 fog delete great-bulkhead
Deleting great-bulkhead i-002391eea4a22a6ba  
    terminating instance i-002391eea4a22a6ba  
    deleting key pair FogROS2KEY-great-bulkhead  
    done.