.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VM::EC2::Instance::Metadata 3pm"
.TH VM::EC2::Instance::Metadata 3pm "2016-06-04" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
VM::EC2::Instance::Metadata \- Object describing the metadata of a running instance
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # For use within a running EC2 instance only!
\&
\& use VM::EC2::Instance::Metadata;
\& my $meta = VM::EC2::Instance::Metadata\->new;
\&
\& # alternatively...
\& my $meta = VM::EC2\->instance_metadata;
\& my $meta = $instance\->metadata;
\&
\& # image information
\& $image_id  = $meta\->imageId;
\& $index     = $meta\->imageLaunchIndex;
\& $path      = $meta\->amiManifestPath;
\& $location  = $meta\->imageLocation;    # same as previous
\& @ancestors = $meta\->ancestorAmiIds;
\& @ancestors = $meta\->imageAncestorIds; # same as previous
\& @codes     = $meta\->productCodes;
\&
\& # launch and runtime information
\& $inst_id   = $meta\->instanceId;
\& $kern_id   = $meta\->kernelId;
\& $rd_id     = $meta\->ramdiskId;
\& $res_id    = $meta\->reservationId;
\& $type      = $meta\->instanceType;
\& $zone      = $meta\->availabilityZone;
\& $userdata  = $meta\->userData;
\& @groups    = $meta\->securityGroups;
\& @keys      = $meta\->publicKeys;
\& $block_dev = $meta\->blockDeviceMapping; # a hashref
\&
\& # Network information
\& $priv_name = $meta\->localHostname;
\& $priv_name = $meta\->privateDnsName;   # same as previous
\& $priv_ip   = $meta\->localIpv4;
\& $priv_ip   = $meta\->privateIpAddress;
\& $mac       = $meta\->mac;
\& $pub_name  = $meta\->publicHostname;
\& $pub_name  = $meta\->dnsName;          # same as previous
\& $pub_ip    = $meta\->publicIpv4;
\& $pub_ip    = $meta\->ipAddress;
\& $interfaces= $meta\->interfaces;       # a hashref
\&
\& # IAM information
\& $iam_info   = $metadata\->iam_info;         # a hashref
\& $iam_role   = $metadata\->iam_role;         # name of the role
\& $credentials= $metadata\->iam_credentials;  # VM::EC2::Security::Credentials object
\&
\& # Undocumented fields
\& $action    = $meta\->instanceAction;
\& $profile   = $meta\->profile;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is an interface to the metadata that is provided to a running
instance via the http://169.254.169.254/latest \s-1URL,\s0 as described in
http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/index.html?instancedata\-data\-categories.html.
.PP
Each metadata object caches its values, so there is no overhead in
calling a method repeatedly. Methods return scalar values, lists and
hashrefs as appropriate.
.PP
The methods from this class should only be called within the context
of a running \s-1EC2\s0 instance. Attempts to call outside of this
context will result in long delays as the module attempts to
connect to an invalid hostname.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$meta = VM::EC2::Instance::Metadata\->\fInew()\fP"
.el .SS "\f(CW$meta\fP = VM::EC2::Instance::Metadata\->\fInew()\fP"
.IX Subsection "$meta = VM::EC2::Instance::Metadata->new()"
.ie n .SS "$meta = $ec2\->\fIinstance_metadata()\fP"
.el .SS "\f(CW$meta\fP = \f(CW$ec2\fP\->\fIinstance_metadata()\fP"
.IX Subsection "$meta = $ec2->instance_metadata()"
.ie n .SS "$meta = $instance\->\fImetadata()\fP"
.el .SS "\f(CW$meta\fP = \f(CW$instance\fP\->\fImetadata()\fP"
.IX Subsection "$meta = $instance->metadata()"
You can create a new metadata object either using this class's \fInew()\fR
constructor, or by calling an \s-1VM::EC2\s0 object's \fIinstance_metadata()\fR
method, or by calling a VM::EC2::Instance object's metadata () method.
.SS "Methods that return scalar values"
.IX Subsection "Methods that return scalar values"
The following methods all return single-valued results:
.IP "Image information:" 4
.IX Item "Image information:"
.Vb 7
\& imageId                \-\- ID of AMI used to launch this instance
\& imageLaunchIndex       \-\- This index\*(Aqs launch index. If four instances
\&                           were launched by one $image\->run_instances()
\&                           call, they will be numbered from 0 to 3.
\& amiManifestPath        \-\- S3 path to the image
\& imageLocation          \-\- Same as amiManifestPath(), for consistency with
\&                           VM::EC2::Image
.Ve
.IP "Launch and runtime information:" 4
.IX Item "Launch and runtime information:"
.Vb 9
\& instanceId             \-\- ID of this instance
\& kernelId               \-\- ID of this instance\*(Aqs kernel.
\& ramdiskId              \-\- This instance\*(Aqs ramdisk ID
\& reservationId          \-\- This instance\*(Aqs reservation ID
\& instanceType           \-\- Machine type, e.g. "m1.small"
\& availabilityZone       \-\- This instance\*(Aqs availability zone.
\& region                 \-\- This instance\*(Aqs region.
\& endpoint               \-\- This instance\*(Aqs endpoint.
\& userData               \-\- User data passed at launch time.
.Ve
.IP "Network information:" 4
.IX Item "Network information:"
.Vb 10
\& localHostname          \-\- The instance hostname corresponding to its
\&                           internal EC2 IP address.
\& privateDnsName         \-\- Same as localHostname(), for consistency with
\&                           VM::EC2::Instance
\& localIpv4              \-\- The instance IP address on the internal EC2 network.
\& privateIpAddress       \-\- Same as localIpv4(), for consistency with 
\&                           VM::EC2::Instance.
\& mac                    \-\- This instance\*(Aqs MAC (ethernet) address.
\& publicHostname         \-\- This instance\*(Aqs public hostname.
\& dnsName                \-\- Same as publicHostname() for consistency with
\&                           VM::EC2::Instance.
\& publicIpv4             \-\- This instance\*(Aqs public IP address.
\& ipAddress              \-\- Same as publicIpv4() for consistency with
\&                           VM::EC2::Instance.
.Ve
.IP "\s-1IAM\s0 information" 4
.IX Item "IAM information"
These routines return information about the instance's \s-1IAM\s0 role, if
any. These calls also provide a temporary security credentials for
making \s-1EC2\s0 calls, as described here:
http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/UsingIAM.html.
.Sp
Note that these routines require installation of the perl \s-1JSON\s0 module, and will
cause a fatal error if this module cannot be loaded.
.Sp
.Vb 7
\& iam_info               \-\- Returns a hash containing the fields \*(AqLastUpdated\*(Aq,
\&                           \*(AqInstanceProfileArn\*(Aq, and \*(AqInstanceProfileId\*(Aq. These
\&                           provide information about the instance\*(Aqs IAM role.
\& iam_role               \-\- Returns the IAM role name for the currently running
\&                           instance.
\& iam_credentials        \-\- Returns a VM::EC2::Security::Credentials object that can
\&                           be passed to VM::EC2\->new(\-security_token=>$credentials).
.Ve
.IP "Unknown information:" 4
.IX Item "Unknown information:"
.Vb 3
\& profile                \-\- An undocumented field that contains the virtualization
\&                           type in the form "default\-paravirtual".
\& instanceAction         \-\- Undocumented metadata field named "instance\-action"
.Ve
.SS "Methods that return lists"
.IX Subsection "Methods that return lists"
The following methods all return lists.
.IP "Image information" 4
.IX Item "Image information"
.Vb 4
\& ancestorAmiIds        \-\- List of  AMIs from which the current one was derived
\& imageAncestorIds      \-\- Same as ancestorAmiIds() but easier to read.
\& productCodes          \-\- List of product codes applying to the image from which
\&                          this instance was launched.
.Ve
.IP "Launch and runtime information" 4
.IX Item "Launch and runtime information"
.Vb 4
\& securityGroups        \-\- List of security groups to which this instance is assigned.
\&                          For non\-VPC instances, this will be the security group
\&                          name. For VPC instances, this will be the security group ID.
\& publicKeys            \-\- List of public key pair names attached to this instance.
.Ve
.SS "Methods that return a hashref"
.IX Subsection "Methods that return a hashref"
The following methods return a hashref for representing complex data structures:
.ie n .IP "$devices = $meta\->blockDeviceMapping" 4
.el .IP "\f(CW$devices\fR = \f(CW$meta\fR\->blockDeviceMapping" 4
.IX Item "$devices = $meta->blockDeviceMapping"
This returns a hashref in which the keys are the names of instance
block devices, such as \*(L"/dev/sda1\*(R", and the values are the \s-1EC2\s0 virtual
machine names. For example:
.Sp
.Vb 8
\& x $meta\->blockDeviceMapping
\& 0  HASH(0x9b4f2f8)
\&   \*(Aq/dev/sda1\*(Aq => \*(Aqroot\*(Aq
\&   \*(Aq/dev/sda2\*(Aq => \*(Aqephemeral0\*(Aq
\&   \*(Aq/dev/sdg\*(Aq => \*(Aqebs1\*(Aq
\&   \*(Aq/dev/sdh\*(Aq => \*(Aqebs9\*(Aq
\&   \*(Aq/dev/sdi\*(Aq => \*(Aqebs10\*(Aq
\&   \*(Aqsda3\*(Aq => \*(Aqswap\*(Aq
.Ve
.Sp
For reasons that are not entirely clear, the swap device is reported
as \*(L"sda3\*(R" rather than as \*(L"/dev/sda3\*(R".
.ie n .IP "$interfaces = $meta\->interfaces" 4
.el .IP "\f(CW$interfaces\fR = \f(CW$meta\fR\->interfaces" 4
.IX Item "$interfaces = $meta->interfaces"
Returns a mapping of all virtual ethernet devices owned by this
instance. This is primarily useful for \s-1VPC\s0 instances, which can have
more than one device. The hash keys are the \s-1MAC\s0 addresses of each
ethernet device, and the values are hashes that have the following
keys:
.Sp
.Vb 9
\& mac
\& localHostname
\& localIpv4s        (an array ref)
\& publicIpv4s       (an array ref)
\& securityGroupIds  (an array ref)
\& subnetId
\& subnetIpv4CidrBlock
\& vpcId
\& vpcIpv4CidrBlock
.Ve
.Sp
For example:
.Sp
.Vb 10
\&                                                                                                                                     D
\& x $meta\->interfaces        
\& 0 HASH(0x9b4f518)
\&   \*(Aq12:31:38:01:b8:97\*(Aq => HASH(0x9eaa090)
\&      \*(AqlocalHostname\*(Aq => \*(AqdomU\-12\-31\-38\-01\-B8\-97.compute\-1.internal\*(Aq
\&      \*(AqlocalIpv4s\*(Aq => ARRAY(0x9b4f8a8)
\&         0  \*(Aq10.253.191.101\*(Aq
\&      \*(Aqmac\*(Aq => \*(Aq12:31:38:01:b8:97\*(Aq
\&      \*(AqpublicIpv4s\*(Aq => ARRAY(0x9ea9e40)
\&         0  \*(Aq184.73.241.210\*(Aq
\&      \*(AqsecurityGroupIds\*(Aq => ARRAY(0x9eaa490)
\&           empty array
\&      \*(AqsubnetId\*(Aq => undef
\&      \*(AqsubnetIpv4CidrBlock\*(Aq => undef
\&      \*(AqvpcId\*(Aq => undef
\&      \*(AqvpcIpv4CidrBlock\*(Aq => undef
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0
VM::EC2::Generic
VM::EC2::BlockDevice
VM::EC2::State::Reason
VM::EC2::State
VM::EC2::Instance
VM::EC2::Tag
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lincoln.stein@gmail.com>.
.PP
Copyright (c) 2011 Ontario Institute for Cancer Research
.PP
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the \s-1GPL \s0(either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to \s-1LICENSE\s0 for the full license text. In addition,
please see \s-1DISCLAIMER\s0.txt for disclaimers of warranty.