Commands for the Snowball Edge Client - AWS Snowcone User Guide

Commands for the Snowball Edge Client

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

Note

The AWS Snowcone device uses the same Snowball Edge CLI commands, but it doesn’t support commands that apply to clustering.

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 AWS 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 AWS Snowcone device on the AWS Snowcone device LCD display. When the AWS 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 AWS Services on AWS Snowcone .

Important

Anyone who can access the configuration file can access the data on your Snowcone device. Managing local access control for this file is one of your administrative responsibilities.

Usage

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

snowballEdge configure

Example Output

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 AWS CLI profiles, see Named Profiles in the AWS 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 AWS 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

Example Output

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

Unlocking an AWS Snowcone Device

To unlock a standalone AWS Snowcone device, run the snowballEdge unlock-device command. These commands authenticate your access to the AWS 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.

Note

To unlock the device associated with your job, the device must be onsite, plugged into power and the network, and turned on. In addition, the LCD display on the front of the AWS Snowcone device must indicate that the device is ready for use.

Usage (configured Snowball Edge client)

snowballEdge unlock-device

Example Single Device Unlock Input

snowballEdge unlock-device

Example Single Device Unlock Output

Your AWS Snowcone device is unlocking. You may determine the unlock state of your device using the describe-device command. Your AWS 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

Example Output

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:

  • NA – No software updates are currently in progress.

  • Downloading – New software is being downloaded.

  • Installing – New software is being installed.

  • Requires Reboot – New software has been installed, and the device needs to be restarted.

    Warning

    We highly recommend that you suspend all activity on the device before you restart the device. Restarting a device stops running instances, interrupts any writing to Amazon S3 buckets on the device, and stops any write operations from the file interface without clearing the cache. All of these processes can result in lost data.

Usage (configured Snowball Edge client)

snowballEdge describe-device-software

Example Output

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

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

Usage (configured Snowball Edge client)

snowballEdge download-updates

Example Output

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

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

Usage (configured Snowball Edge client)

snowballEdge install-updates

Example Output

Installation started.

snowballEdge reboot-device – Reboots the device.

Warning

We highly recommend that you suspend all activity on the device before you restart the device. Restarting a device stops running instances, interrupts any writing to Amazon S3 buckets on the device, and stops any write operations from the file interface without clearing the cache. All of these processes can result in lost data.

Usage (configured Snowball Edge client)

snowballEdge reboot-device

Example Output

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]

Example Output

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

Example Output

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 AWS CLI or with an AWS 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 AWS Identity and Access Management (IAM) permissions in the AWS Cloud.

Note

If you're using the AWS CLI with Snowball, you must use these credentials when you configure the CLI. For information on configuring credentials for the CLI, see Quick Configuration in the AWS Command Line Interface User Guide.

Usage (configured Snowball Edge client)

snowballEdge list-access-keys

Example Output

{ "AccessKeyIds" : [ "AKIAIOSFODNN7EXAMPLE" ] }

Usage (configured Snowball Edge client)

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

Example Output

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

Starting a Service on Your Snowcone

Snowcone supports multiple services, including compute instances, the NFS file interface, Amazon EC2, and AWS 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

Example Output

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

Stopping a Service on Your Snowcone

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

Warning

Data loss can occur if the file interface is stopped before remaining buffered data is written to the device.

Usage (configured Snowball Edge client)

snowballEdge stop-service --service-id service_id

Example Output

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

Getting Your Certificate for Transferring Data

To transfer data to a Snowcone, use the NFS file interface or AWS 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 again using the get-certificate command.

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

  • list-certificates – Lists the Amazon Resource Names (ARNs) for the certificates available for use.

    Usage (configured Snowball Edge client)

    snowballEdge list-certificates

    Example Output

    { "Certificates" : [ { "CertificateArn" : "arn:aws:snowball-device:::certificate/78EXAMPLE516EXAMPLEf538EXAMPLEa7", "SubjectAlternativeNames" : [ "192.0.2.0" ] } ] }
  • get-certificate – Gets a specific certificate, based on the ARN provided.

    Usage (configured Snowball Edge client)

    snowballEdge get-certificate --certificate-arn arn:aws:snowball-device:::certificate/78EXAMPLE516EXAMPLEf538EXAMPLEa7

    Example Output

    -----BEGIN CERTIFICATE----- Certificate -----END CERTIFICATE-----

AWS 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:

  • list-logs – Returns a list of logs in JSON format. This list reports the size of the logs in bytes, the ARN for the logs, the service ID for the logs, and the type of logs.

    Usage (configured Snowball Edge client)

    snowballEdge list-logs

    Example Output

    { "Logs" : [ { "LogArn" : "arn:aws:snowball-device:::log/s3-storage-JIEXAMPLE2f-1234-4953-a7c4-dfEXAMPLE709", "LogType" : "SUPPORT", "ServiceId" : "datasync", "EstimatedSizeBytes" : 53132614 }, { "LogArn" : "arn:aws:snowball-device:::log/fileinterface-JIDEXAMPLEf-1234-4953-a7c4-dfEXAMPLE709", "LogType" : "CUSTOMER", "ServiceId" : "nfs", "EstimatedSizeBytes" : 4446 }] }
  • get-log – Downloads a copy of a specific log from the Snowcone to your server at a specified path. CUSTOMER logs are saved in the .zip format, and you can extract this type of log to view its contents. SUPPORT logs are encrypted and can only be read by AWS Support engineers. You have the option of specifying a name and a path for the log.

    Usage (configured Snowball Edge client)

    snowballEdge get-log --log-arn arn:aws:snowball-device:::log/fileinterface-JIDEXAMPLEf-1234-4953-a7c4-dfEXAMPLE709

    Example Output

    Logs are being saved to download/path/snowball--logs-1515EXAMPLE88.bin
  • get-support-logs – Downloads a copy of all the SUPPORT type of logs from the Snowcone to your service at a specified path.

    Usage (configured Snowball Edge client)

    snowballEdge get-support-logs

    Example Output

    Logs are being saved to download/path/snowball--logs-1515716135711.bin
Important

CUSTOMER type might contain sensitive information about your own data. To protect this potentially sensitive information, we strongly suggest that you delete these logs after you're done with them.

Getting Device Status

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

  • describe-device

    Usage (configured Snowball Edge client)

    snowballEdge describe-device

    Example Output

    { "DeviceId" : "JID-EXAMPLE12345-123-456-7-890", "UnlockStatus" : { "State" : "UNLOCKED" }, "ActiveNetworkInterface" : { "IpAddress" : "192.0.2.0" }, "PhysicalNetworkInterfaces" : [ { "PhysicalNetworkInterfaceId" : "s.ni-EXAMPLEd9ecbf03e3", "PhysicalConnectorType" : "RJ45", "IpAddressAssignment" : "STATIC", "IpAddress" : "0.0.0.0", "Netmask" : "0.0.0.0", "DefaultGateway" : "192.0.2.1", "MacAddress" : "EX:AM:PL:E0:12:34" }, { "PhysicalNetworkInterfaceId" : "s.ni-EXAMPLE4c3840068f", "PhysicalConnectorType" : "RJ45", "IpAddressAssignment" : "STATIC", "IpAddress" : "0.0.0.0", "Netmask" : "0.0.0.0", "DefaultGateway" : "192.0.2.2", "MacAddress" : "EX:AM:PL:E0:56:78" }, { "PhysicalNetworkInterfaceId" : "s.ni-EXAMPLE0a3a6499fd", "PhysicalConnectorType" : "SFP_PLUS", "IpAddressAssignment" : "DHCP", "IpAddress" : "192.168.1.231", "Netmask" : "255.255.255.0", "DefaultGateway" : "192.0.2.3", "MacAddress" : "EX:AM:PL:E0:90:12" } ] }

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.

  • list-services

    Usage (configured Snowball Edge client)

    snowballEdge list-services

    Example Output

    { "ServiceIds" : [ "nfs", "datasync", "ec2" ] }
  • describe-service

    This command returns a status value for a service. It also includes state information that might be helpful in resolving issues you encounter with the service. Those states are as follows.

    • ACTIVE – The service is running and available for use.

    • ACTIVATING – The service is starting up, but it is not yet available for use.

    • DEACTIVATING – The service is in the process of shutting down.

    • INACTIVE – The service is not running and is not available for use.

    Usage (configured Snowball Edge client)

    snowballEdge describe-service --service-id service-id

    Example Output

    { "ServiceId" : "ec2", "Status" : { "State" : "ACTIVE" }, "Storage" : { "TotalSpaceBytes" : 99608745492480, "FreeSpaceBytes" : 99608744468480 }, "Endpoints" : [ { "Protocol" : "http", "Port" : 8080, "Host" : "192.0.2.0" }, { "Protocol" : "https", "Port" : 8443, "Host" : "192.0.2.0", "CertificateAssociation" : { "CertificateArn" : "arn:aws:snowball-device:::certificate/6d955EXAMPLEdb71798146EXAMPLE3f0" } } ] }

Launching AWS DataSync AMI

Launch the AWS DataSync AMI on Snowcone

Usage (configured Snowball Edge client)

Note that 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": "AWS DataSync AMI for online data transfer", "EnaSupport": false, "Name": "scn-datasync-ami", "RootDeviceName": "/dev/sda" }
aws ec2 describe-instances --endpoint \ http://${snowcone_ip}:8008

Example Output

{ "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

Example Output

{ "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

Important

Don't start the NFS service if you intend to use Amazon Elastic Block Store (Amazon EBS). The first time NFS is started, all storage is allocated to NFS. It is not possible to reallocate NFS storage to Amazon EBS, even if the NFS service is stopped.

Note

You can provide CIDR blocks for IP ranges that are allowed to mount the NFS shares exposed by the device. For example, 10.0.0.0/16. If you don't provide allowed CIDR blocks, all mount requests will be denied.

Be aware that data transferred through NFS is not encrypted in transit.

Other than the allowed hosts by CIDR blocks, Snowcone doesn't provide an authentication or authorization mechanism for the NFS shares.

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

Example Output

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 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 AWS Operator Debugging

  • enable-local-aws-operator-debugging—Enables device for local AWS operator debugging by opening SSH port 22.

Usage (configured Snowball Edge client)

snowballEdge enable-local-aws-operator-debugging

Disabling Local AWS Operator Debugging

  • disable-local-aws-operator-debugging—Disables device for local AWS operator debugging by closing SSH port 22. By default, SSH port 22 is closed. When the Snowcone device is turned off or is power cycled, local AWS operator debugging is disabled.

Usage (configured Snowball Edge client)

snowballEdge disable-local-aws-operator-debugging

Creating a Direct Network Interface

  • create-direct-network-interface —Creates a direct network interface (DNI). Creates a direct network interface to use with Amazon EC2 compute instances on your device. You can find the direct network interfaces available on your by using the describe-direct-network-interfaces command.

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 Direct Network Interface

  • describe-direct-network-interface —Gets the direct network interfaces on your device. A direct network interface can be used to configure networking for EC2 compute instances and services on your device. You can create a new direct network interface by using the create-direct-network-interface command.

Usage (configured Snowball Edge client)

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

Updating a Direct Network Interface

  • update-direct-network-interface —Updates a direct network interface. Use update a direct network interface that will be used with EC2 compute instances on your device. You can find the direct network interfaces that are available on your device by using the describe-direct-network-interfaces command. When you are modifying a network interface that is attached to an EC2 instance, the interface will first be detached.

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

  • delete-direct-network-interface—Deletes a direct network interface that is no longer in use. To delete a direct network interface associated with your EC2 compute instance, you must first disassociate the direct network interface from your instance.

Usage (configured Snowball Edge client)

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