ec2uploadimg.1

NAME
ec2uploadimg - Upload a compressed raw image file to Amazon EC2 and create a snapshot or an AMI

SYNOPSIS
ec2uploadimg [option] PATH_TO_FILE

DESCRIPTION
ec2uploadimg Upload a compressed raw image to Amazon EC2 using an existing EC2 AMI and create a snapshot or register a new AMI from the image. The apparent size of the raw image is recommended to be 10 GB or less. It is expected that the raw image has 1 partition, i.e. the root partition is /dev/sda1. The process of creating the image is as follows: - start an instance - create a storage volume and attach it to the running instance - create volume that will be the new root and attach it to the running instance - upload the image - unpack the image and dump it to the new root volume - detach the new root volume and create a snapshot - register a new AMI - clean up

OPTIONS

-a --account ACCOUNT_NAME
    Specifies the account to use to connect to EC2. The account is specified in the config file ~/.ec2utils.conf. The account is specified as a section with [account-ACCOUNT_NAME] delimiter. The options of the sections are access_key_id secret_access_key ssh_key_name ssh_private_key This allows the program to connect to EC2. If the access_key_id and/or secret_access_key are not found in ~/.ec2utils.conf, the search will use the ACCOUNT_NAME to look for a matching section [profile ACCOUNT_NAME] in ~/.aws/config or [ACCOUNT_NAME] in ~/.aws/credentials.

--access-id AWS_ACCESS_KEY
    Specifies the AWS access key and overrides the value given for the account with the access_key_id in the configuration file.

-B --backing-store EC2_BACKING_STORE
    Specifies the backing store type for the AMI to be created. The uploaded image is an EBS (Elastic Block Store) backed image and my be registered as using SSD or Magnetic media as the backing store when being launched. Possible values are ssd, mag, or one of the known storage classes. The generic identifier ssd is mapped to the gp2 storage class, and the mag identifier is mapped to the standard storage class.

--billing-codes BILLING_CODES
    Specifies the billing product codes to apply to the image during registration. This functionality is restricted to specific accounts within EC2.

--boot-kernel AWS_AKI_ID
    Specifies the aki_id of the boot kernel that should be used when registering a Para-virtual image. This option overrides the aki_i386, aki_x86_64, or g2_aki_x86_64 value in the configuration file.

-d --description IMAGE_DESCRIPTION
    Specifies a description for the image. The description will also be used for the snapshot.

-e --ec2-ami AWS_AMI_ID
    Specify the AMI ID of the image to launch that will be used to perform the upload operation. This value overrides the value given with the ami option for a given region in the configuration file.

-f --file CONFIG_FILE
    Specifies the configuration file to use. The default is ~/.ec2utils.conf

--grub2
    Specifies if the image being uploaded and registered as AMI uses the GRUB2 bootloader. In some cases GRUB2 is referred to as GRUB and the first incarnation of GRUB is referred to as GRUB-Legacy. Setting this switch will select the g2_aki_x86_64 value from the configuration file or will use the value given with --boot-kernel as the aki ID when a para virtual image is being registered.

-m --machine ARCH
    Specifies the architecture for the VM to be created. Supported values are arm64 , i386 or x86_64

-n --name IMAGE_NAME
    Specifies the name of the AMI to be registered.

-p --private-key-file PRIVATE_KEY
    Specifies the path to the private ssh key file to use to connect with the instance that is being used to upload the raw image. This option overrides the value of the ssh_private_key in the configuration file.

-r --regions EC2_REGIONS
    A comma separated list of Amazon EC2 regions, or a single region.

--root-volume-size
    Specify the size in GB of the new root volume for the AMI being created. It is recommended to keep the root volume size to 10GB or less.

--ssh-key-pair AWS_KEY_PAIR_NAME
    Specifies the key-pair name to use when launching the instance that is used to upload the raw image. The specified private key file must correlate to the key pair name given with this argument. This value overrides the value given for the account with the ssh_key_name in the configuration file.

-s --secret-key AWS_SECRET_KEY
    Specifies the AWS secret access key and overrides the value given for the account with the secret_access_key in the configuration file.

--security-group-ids AWS_SECURITY_GROUP_IDS
    Specifies a list of security group ids to apply to the helper instance. At least one of the groups must have port 22 open to support ssh connections.

--session-token AWS_SESSION_TOKEN
    Specifies the AWS session token. Only necessary when using temporary credentials.

--snaponly
    When this argument is set only a snapshot of the uploaded image will be created. The snapshot may then be used in a separate operation to register an AMI.

--use-snapshot
    When this argument is set the image will be created from an existing snapshot. The snapshotID is specified as the source variable.

--sriov-support
    Enable SRIOV support for HVM images. This implies that the appropriate driver has to be included in the image.

--ssh-timeout SSH_TIME_OUT
    Specifies the amount of time to wait in seconds to establish an SSH connection with the helper instance.

-t --type AWS_UPLOAD_INST_TYPE
    Specifies the instance type to launch for the instance being used to upload the image. This value overrides the value given with the instance_type option for a given region in the configuration file.

-u --user AWS_INSTANCE_USER
    Specifies the user to use to connect to the instance being used to upload the image. This value overrides the value given with the user option for a given region in the configuration file.

--use-private-ip
    Use the private IP of the helper instance to upload the new image. This is helpful when an image is to be created and only a private VPC is available.

--use-root-swap
    Create the new image using the root swap method. The helper instance used to upload the image will be stopped and the created image volume will be attached to the helper instance. A new image is registered from the helper instance. This method of image creation is useful when meta data associated with the image used to launch the helper instance needs to be transferred to the new image. The new image creation may time out as a copy of the complete image disk needs to be made. The code will then skip the clean up and a storage volume, a target root volume and a stopped instance will remain in the users account.

-V --virt-type AWS_VIRT_TYPE
    Specifies the virtualization type to use for the image to be registered. Possible values are para (default) or hvm.

--vpc-subnet-id VPC_SUBNET_ID
    Specify the VPC subnet ID into which the helper instance should be launched. This option is useful if no default VPC is configured or it is desired to launch the helper instance into a private subnet of the VPC. For the use of a private subnet it may also be necessary to use the --use-private-ip command line option. The ID should start with subnet-. Instance type and subnets are to a certain degree linked in that it may not be possible to launch the configured helper instance type outside a VPC subnet. Therefore, if the --vpc-subnet-id is not specified on the command line and neither --ec2-ami or --instance-id are specified on the command line an attempt will be made to retrieve the subnet-id from the configuration. The configuration is subnet_id_REGION where region is one of the known region identifiers such as us-east-1. The region given with the --regions command line argument is used. Specifying multiple regions with the --regions argument and using the --vpc-subnet-id argument is incompatible. When targeting multiple regions the subnet-id must be set in the configuration file.

--wait-count AWS_WAIT_COUNT
    Specifies the number of times to wait for the AWS operation timeout. The default value is 1 which is equivalent to 600 seconds.

EXAMPLE
ec2uploadimg --account example -d "My first image" -m x86_64 -n my_linux_image -r us-east-1 PATH_TO_COMPRESSED_FILE Will upload the raw disk image contained in the PATH_TO_COMPRESSED_FILE and will register a new AMI from the image.

AUTHOR
Robert Schweikert (rjschwei@suse.com)