Commands for the Snowball Edge Client

Following, you can find information about Snowball Edge client commands, including examples of use and sample outputs.

Configuring a Profile for the Snowball Edge Client

Every time you run a command for the Snowball Edge client, you provide your manifest file, unlock code, and an IP address. You can get the first two of these from the Amazon Snow Family Management Console or the job management API. For more information about getting your manifest and unlock code, see Getting Credentials.

You have the option of using the snowballEdge configure command to store the path to the manifest, the 29-character unlock code, and the endpoint as a profile. After configuration, you can use other Snowball Edge client commands without having to manually enter these values for a particular job. After you configure the Snowball Edge client, the information is saved in a plaintext JSON format to home directory/.aws/snowball/config/snowball-.config.

The endpoint is the IP address, with https:// added to it. You can locate the IP address for the Amazon Snowcone device on the Amazon Snowcone device LCD display. When the Amazon Snowcone device is connected to your network for the first time, it automatically gets a DHCP IP address, if a DHCP server is available. If you want to use a different IP address, you can change it from the LCD display. For more information, see Using Amazon Services on Amazon Snowcone.

Usage

You can use this command in two ways: inline, or when prompted. This usage example shows the prompted method.

snowballEdge configure

Configuration will be stored at home directory\.aws\snowball\config\snowball-.config
Snowcone  Manifest Path: Path/to/manifest/file
Unlock Code: 29 character unlock code
Default Endpoint: https://192.0.2.0

You can have multiple profiles if you have multiple jobs at once. For more information about multiple Amazon CLI profiles, see Named Profiles in the Amazon Command Line Interface User Guide.

Getting Your QR Code for NFC Validation

You can use this command to generate a device-specific QR code for use with the Amazon Snowcone Verification App. You can download this app from the Apple App Store or Google Play store. For more information about NFC validation, see Validating NFC Tags.

Usage

snowballEdge get-app-qr-code --output-file ~/downloads/snowball-qr-code.png

QR code is saved to ~/downloads/snowball-qr-code.png

Unlocking an Amazon Snowcone Device

To unlock a standalone Amazon Snowcone device, run the snowballEdge unlock-device command. These commands authenticate your access to the Amazon Snowcone device.

When you run one of these unlock commands, you can manually enter the path to the manifest file, the 29-character unlock code, and the IP address for your standalone device. This process can get tedious, so we recommend that you configure your Snowball Edge client instead. If you've already configured the Snowball Edge client, then you only need to enter the command itself without the path to the manifest, the unlock code, or the IP address.

Usage (configured Snowball Edge client)

snowballEdge unlock-device

Your Amazon Snowcone device is unlocking. You may determine the unlock state of your device using the describe-device command. Your Amazon Snowcone device will be available for use when it is in the UNLOCKED state.

Updating a Snowcone

Use the following commands to download and install updates for your Snowcone device. For procedures that use these commands, see Updating a Snowcone .

snowballEdge check-for-updates – Returns version information about the Snowball software available in the cloud, and the current version installed on the device.

Usage (configured Snowball Edge client)

snowballEdge check-for-updates

Latest version: 102
Installed version: 101

snowballEdge describe-device-software – Returns the current software version for the device. Additionally, if the update is being downloaded, the download state is also displayed. If a software update is in progress, the version manifest of update, and state of installation is also displayed. Following is a list of possible outputs:

Usage (configured Snowball Edge client)

snowballEdge describe-device-software

Installed version: 101
Installing version: 102
Install State: Downloading

snowballEdge download-updates – Starts downloading the latest software updates for your Snowcone device.

Usage (configured Snowball Edge client)

snowballEdge download-updates

Download started. Run describe-device-software API for additional information.

snowballEdge install-updates – Starts installing the latest software updates for your Snowcone device that were already downloaded.

Usage (configured Snowball Edge client)

snowballEdge install-updates

Installation started.

snowballEdge reboot-device – Reboots the device.

Usage (configured Snowball Edge client)

snowballEdge reboot-device

Rebooting device now.

snowballEdge configure-auto-update-strategies – Configures an automatic update strategy.

Usage (configured Snowball Edge client)

snowballEdge configure-auto-update-strategy --auto-check autoCheck [--auto-check-frequency
autoCheckFreq] --auto-download autoDownload
[--auto-download-frequency autoDownloadFreq]
--auto-install autoInstall
[--auto-install-frequency autoInstallFreq]
--auto-reboot autoReboot [--endpoint
endpoint]

Successfully configured auto update strategy. Run describe-auto-update-strategies for additional information.

snowballEdge describe-auto-update-strategies – Returns any currently configured automatic update strategy.

Usage (configured Snowball Edge client)

snowballEdge describe-auto-update-strategies

auto-update-strategy {[
auto-check:true,
auto-check-frequency: "0 0 * * FRI", // CRON Expression String, Every Friday at midnight
auto-download:true,
auto-download-frequency: "0 0 * * SAT", // CRON Expression String, Every Saturday at
midnight
auto-install:true,
auto-install-frequency: "0 13 * * Sun", // CRON Expression String, Every Saturday at
midnight
auto-reboot: false;
]}

Getting Credentials

Using the snowballEdge list-access-keys and snowballEdge get-secret-access-key commands, you can get your local credentials. You use these to authenticate your requests when using the Amazon CLI or with an Amazon SDK. These credentials are only associated with an individual job for Snowcone, and you can use them only on the device. The device doesn't have any Amazon Identity and Access Management (IAM) permissions in the Amazon Web Services Cloud.

For more information see Amazon credentials and using the Amazon EC2 Endpoint.

Usage (configured Snowball Edge client)

snowballEdge list-access-keys

{
  "AccessKeyIds" : [ "AKIAIOSFODNN7EXAMPLE" ]
}

Usage (configured Snowball Edge client)

snowballEdge get-secret-access-key --access-key-id Access Key

[snowballEdge]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Starting a Service on Your Snowcone Device

Snowcone supports multiple services, including compute instances, the NFS file interface, Amazon EC2, and Amazon DataSync. You can start these services with the snowballEdge start-service command. To get the service ID for each service, you can use the snowballEdge list-services command.

Before you run this command, create a single virtual network interface to bind to the service that you're starting. For more information, see Creating a Virtual Network Interface.

Usage (configured Snowball Edge client)

snowballEdge start-service --service-id service_id --virtual-network-interface-arns virtual-network-interface-arn

Starting the Amazon service on your Snowball Edge . You can determine the status of the Amazon service using the describe-service command.

Stopping a Service on Your Snowcone Device

To stop a service running on your Snowcone device, you can use the snowballEdge stop-service command. The Amazon EC2 services cannot be stopped.

Usage (configured Snowball Edge client)

snowballEdge stop-service --service-id service_id

Stopping the Amazon service on your Snowball . You can determine the status of the Amazon service using the describe-service command.

Getting Your Certificate for Transferring Data

To transfer data to a Snowcone device, use the NFS file interface or Amazon DataSync. If you unlock your Snowcone device with a different IP address, a new certificate is generated, and the old certificate is no longer valid to use with the endpoint. You can get the new, updated certificate from the Snowcone device again using the get-certificate command.

You can list these certificates and download them from your Snowcone device with the following commands:

Amazon Snowcone Logs

When you transfer data between your on-premises data center and a Snowcone device, logs are automatically generated. If you encounter unexpected errors during data transfer to the device, you can use the following commands to save a copy of the logs to your local server.

There are three commands related to logs:

Getting Device Status

You can determine the status and general health of your Snowcone device with the following Snowball Edge client commands:

Getting Service Status

You can determine the status and general health of the services running on a Snowcone device by using the describe-service command. You can first run the list-services command to see what services are running.

Launching the Amazon DataSync AMI

Launch the Amazon DataSync AMI on Snowcone.

Usage (configured Snowball Edge client)

Amazon DataSync must be launched with the snc1.medium instance type. Launching DataSync with a different instance type can result in an unstable operation and potential data loss. Use the describe-images command to find the image to launch an instance from. The output looks like the following.

{
  "ImageId": "s.ami-0c046f119de4f752f",
  "Public": false,
  "State": "AVAILABLE",
  "BlockDeviceMappings": [
    {
      "DeviceName": "/dev/sda",
      "Ebs": {
        "DeleteOnTermination": true,
        "Iops": 0,
        "SnapshotId": "s.snap-0d7558ce444ab09bf",
        "VolumeSize": 20,
        "VolumeType": "sbp1"
      }
    }
  ],
  "Description": "Amazon DataSync AMI for online data transfer",
  "EnaSupport": false,
  "Name": "scn-datasync-ami",
  "RootDeviceName": "/dev/sda"
}

aws ec2 describe-instances --endpoint http://${snowcone_ip}:8008

{
    "Reservations": [
        {
            "Instances": [
                {
                    "AmiLaunchIndex": 0,
                    "ImageId": "s.image id",
                    "InstanceId": "s.instance id",
                    "InstanceType": "snc1.medium",
                    "LaunchTime": "2020-03-06T18:58:36.609Z",
                    "PrivateIpAddress": "ip address",
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    },
                    "BlockDeviceMappings": [
                        {
                            "DeviceName": "/dev/sda",
                            "Ebs": {
                                "AttachTime": "2020-03-06T19:14:21.336Z",
                                "DeleteOnTermination": true,
                                "Status": "attached",
                                "VolumeId": "s.volume id"
                            }
                        }
                    ],
                    "EbsOptimized": false,
                    "EnaSupport": false,
                    "RootDeviceName": "/dev/sda",
                    "SecurityGroups": [
                        {
                            "GroupName": "default",
                            "GroupId": "s.security group id"
                        }
                    ],
                    "SourceDestCheck": false,
                    "CpuOptions": {
                        "CoreCount": 2,
                        "ThreadsPerCore": 1
                    }
                }
            ],
            "ReservationId": "s.r-80c8ee6b041b29eb4"
        },
    ]
}

Run the instance.

aws ec2 run-instances --image-id s.ami id \--instance-type snc1.medium --endpoint http://${snowcone_ip}:8008

{
    "Instances": [
        {
            "AmiLaunchIndex": 0,
            "ImageId": "s.ami-0623310b494365cc5",
            "InstanceId": "s.i-80c8ee6b041b29eb4",
            "InstanceType": "snc1.medium",
            "State": {
                "Code": 0,
                "Name": "pending"
            },
            "EbsOptimized": false,
            "EnaSupport": false,
            "RootDeviceName": "/dev/sda",
            "SecurityGroups": [
                {
                    "GroupName": "default",
                    "GroupId": "s.sg-80c8ee6b041b29eb4"
                }
            ],
            "SourceDestCheck": false,
            "CpuOptions": {
                "CoreCount": 2,
                "ThreadsPerCore": 1
            }
        }
    ],
    "ReservationId": "s.r-80c8ee6b041b29eb4"
}

Starting NFS and Restricting Access

Start NFS with the snowballEdge start-service command. To get the service ID for the NFS service, you can use the snowballEdge list-services command.

Before you run this command, create a single virtual network interface to bind to the service that you're starting. For more information, see Creating a Virtual Network Interface. You can restrict access to your file shares and data in your Amazon S3 buckets and see what restrictions are currently in place. You do this by allocating CIDR blocks for allowed hosts that can access your file share and S3 buckets when you start the NFS service.

Usage (configured Snowball Edge client)

snowballEdge start-service --service-id nfs --virtual-network-interface-arns arn:aws:snowball-device:::interface/s.ni-12345fgh45678j --service-configuration AllowedHosts=ip address-1/32,ip address-2/24

Starting the service on your Snowball Edge. You can determine the status of the service using the describe-service command.

Restricting Access to NFS Shares When NFS is Running

You can restrict access your file shares and data in your Amazon S3 buckets after you have started NFS. You can see what restrictions are currently in place, and give each bucket different access restrictions. You do this by allocating CIDR blocks for hosts that can access your file share and S3 buckets when you start the NFS service. The following is an example command.

Usage (configured Snowball Edge client)

snowballEdge start-service \
    --service-id nfs \
    --virtual-network-interface-arns virtual-network-interface-arn --service-configuration AllowedHosts=ip-address-1/32,ip-address-1/24

To see the current restrictions, use the describe-service command.

 snowballEdge describe-service --service-id nfs

Getting the Export Path for an Amazon S3 Bucket

There is no specific Snowcone command for getting the export path of an Amazon S3 bucket. The format of the export path looks like the following.

/buckets/bucket-name.

Enabling Local Amazon Operator Debugging

Usage (configured Snowball Edge client)

snowballEdge enable-local-aws-operator-debugging

Disabling Local Amazon Operator Debugging

Usage (configured Snowball Edge client)

snowballEdge disable-local-aws-operator-debugging

Creating a Direct Network Interface

Usage (configured Snowball Edge client)

create-direct-network-interface [--endpoint endpoint] [--instance-id instanceId] [--mac macAddress]
                                [--manifest-file manifestFile] [--physical-network-interface-id physicalNetworkInterfaceId] 
                                [--profile profile] [--unlock-code unlockCode] [--vlan vlanId]

Getting Information About a Direct Network Interface

Usage (configured Snowball Edge client)

describe-direct-network-interfaces [--endpoint endpoint] [--manifest-file manifestFile] [--profile profile] [--unlock-code unlockCode]

Updating a Direct Network Interface

Usage (configured Snowball Edge client)

update-direct-network-interface [--direct-network-interface-arn directNetworkInterfaceArn] [--endpoint endpoint] 
                                [--mac macAddress]
                                [--manifest-file manifestFile] [--profile profile] [--unlock-code unlockCode] 
                                [--vlan vlanId] [--attach-instance-id instanceId | --detach]

Deleting a Direct Network Interface

Usage (configured Snowball Edge client)

delete-direct-network-interface [--direct-network-interface-arn directNetworkInterfaceArn] [--endpoint endpoint] 
                                [--manifest-file manifestFile] [--profile profile] [--unlock-code unlockCode]                                 

Checking feature status

To list the status of features available on your device, including Amazon Snow Device Management, which allows you to manage your Snowcone device and local Amazon services remotely, use the describe-features command.

RemoteManagementState indicates the status of Snow Device Management and returns one of the following states:

Usage (configured Snowball Edge client)

snowballEdge describe-features 
--manifest-file manifest.bin path 
--unlock-code unlock-code 
--endpoint https://device-local-ip:9091

Example Output

{
  "RemoteManagementState" : String
}
            

Changing feature status

To change the status of the features available on your Amazon Snowcone device, use the set-features command. To enable or disable Amazon Snow Device Management, which allows you to manage your Snowcone device and local Amazon services remotely, use the --remote-management-state parameter. The device must be unlocked before you run this command.

You can set Snow Device Management to the following states:

Usage (configured Snowball Edge client)

snowballEdge set-features
--remote-management-state INSTALLED_AUTOSTART
--manifest-file ./JID2bf11d5a-fict-414a-b5b1-3bf7e6a6e83d_manifest.bin
--unlock-code 73bb0-f8ke1-69a4a-f4288-4f88d
--endpoint https://10.0.0.25

Example Output

{
  "RemoteManagementState" : "INSTALLED_AUTOSTART"
}
            

Setting Time Servers

You can set up an external Network Time Protocol (NTP) server. You can use the NTP CLI commands when the device is in both locked and unlocked states. The manifest and unlock code are required. You can set these either with the snowballEdge configure command or by using the --manifest-file and --unlock-code options. Note that you can use the snowballEdge CLI on both Amazon Snowcone Edge and Amazon Snowcone.

It is your responsibility to provide a secure NTP time server. To set which NTP time servers the device connects to, use the update-time-servers CLI command.

Usage

snowballEdge update-time-servers time.google.com

Updating time servers now.

Checking Time Sources

To see which NTP time sources the device are currently connected to, use the describe-time-sources Snowball Edge CLI command.

Usage

snowballEdge describe-time-sources

{
  "Sources" : [ {
    "Address" : "172.31.2.71",
    "State" : "LOST",
    "Type" : "PEER",
    "Stratum" : 10
  }, {
    "Address" : "172.31.3.203",
    "State" : "LOST",
    "Type" : "PEER",
    "Stratum" : 10
  }, {
    "Address" : "172.31.0.178",
    "State" : "LOST",
    "Type" : "PEER",
    "Stratum" : 10
  }, {
    "Address" : "172.31.3.178",
    "State" : "LOST",
    "Type" : "PEER",
    "Stratum" : 10
  }, {
    "Address" : "216.239.35.12",
    "State" : "CURRENT",
    "Type" : "SERVER",
    "Stratum" : 1
  } ]
}

The describe-time-sources command returns a list of time source states. Each time source state contains the Address, State, Type, and Stratum fields. Following are the meanings of these fields.

An NTP time source can either be a server or a peer. A server can be set by the user with the update-time-servers command, whereas a peer could only be other Snowball Edge devices in the cluster. In the example output, describe-time-sources is called on a Snowball Edge that is in a cluster of 5. The output contains 4 peers and 1 server. The peers have a stratum of 10 while the server has a stratum of 1; therefore, the server is selected to be the current time source.