.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 >0, 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 "GBROWSE_AWS_BALANCER 1p"
.TH GBROWSE_AWS_BALANCER 1p "2023-12-07" "perl v5.36.0" "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"
gbrowse_aws_balancer.pl \- Load balance GBrowse using Amazon Web Service instances
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Launch the balancer in the foreground
.PP
.Vb 3
\& % gbrowse_aws_balancer.pl \-\-conf /etc/gbrowse2/aws_balancer.conf \e
\& \-\-access_key XYZZY \e
\& \-\-secret_key Plugh
.Ve
.PP
Launch the balancer in the background as a daemon:
.PP
.Vb 7
\& % gbrowse_aws_balancer.pl \-\-background \e
\& \-\-conf /etc/gbrowse2/aws_balancer.conf \e
\& \-\-access_key XYZZY \e
\& \-\-secret_key Plugh \e
\& \-\-logfile /var/log/gbrowse/aws_balancer.log \e
\& \-\-pidfile /var/run/aws_balancer.pid \e
\& \-\-user nobody
.Ve
.PP
Kill a running balancer daemon:
.PP
.Vb 7
\& % gbrowse_aws_balancer.pl \-\-kill \e
\& \-\-conf /etc/gbrowse2/aws_balancer.conf \e
\& \-\-access_key XYZZY \e
\& \-\-secret_key Plugh \e
\& \-\-logfile /var/log/gbrowse/aws_balancer.log \e
\& \-\-pidfile /var/run/aws_balancer.pid \e
\& \-\-user nobody
.Ve
.PP
Use the init script:
.PP
.Vb 4
\& % sudo /etc/init.d/gbrowse\-aws\-balancer start
\& % sudo /etc/init.d/gbrowse\-aws\-balancer restart
\& % sudo /etc/init.d/gbrowse\-aws\-balancer stop
\& % sudo /etc/init.d/gbrowse\-aws\-balancer status
.Ve
.PP
Synchronize the master with the slave image:
.PP
.Vb 4
\& % sudo gbrowse_sync_aws_slave.pl \-c /etc/gbrowse2/aws_balancer.conf
\& syncing data....done
\& data stored in snapshot(s) snap\-12345
\& updated conf file, previous version in /etc/gbrowse2/aws_balancer.conf.bak
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This script launches a process that monitors the load on the local
GBrowse instance. If the load exceeds certain predefined levels, then
it uses Amazon web services to launch one or more GBrowse slave
instances. The work of rendering tracks is then handed off to these
instances, reducing the load on the local instance. Slave instances
are implemented using Amazon's spot instance mechanism, which allows
you to run \s-1EC2\s0 instances at a fraction of the price of a standard
on-demand instance.
.PP
Load balancing is most convenient to run in conjunction with a GBrowse
instance running within the Amazon Web Service \s-1EC2\s0 cloud, but it can
also be used to supplement an instance running on local hardware. The
sections below describe the configuration needed for these two
scenarios.
.PP
Note that this script requires you to have an Amazon Web Services
account, and for the \s-1VM::EC2\s0 Perl module to be installed on the
machine that is running this script.
.SH "COMMAND-LINE OPTIONS"
.IX Header "COMMAND-LINE OPTIONS"
Options can be abbreviated. For example, you can use \-a for
\&\-\-access_key:
.PP
.Vb 10
\& \-\-access_key EC2 access key
\& \-\-secret_key EC2 secret key
\& \-\-conf Path to balancer configuration file
\& \-\-pidfile Path to file that holds daemon process ID
\& \-\-logfile Path to file that records log messages
\& \-\-user User to run daemon under (script must be
\& started as root)
\& \-\-verbosity Logging verbosity. 0=least, 3=most.
\& \-\-background Go into the background and run as daemon.
\& \-\-kill Kill a previously\-launched daemon. Must provide
\& the same \-\-pidfile argument as used when
\& the daemon was started.
\& \-\-ssh_key Enable ssh login on the slave(s) using the specified
\& AWS ssh keypair. Login will only be available
\& from the host this script is run on.
.Ve
.SH "PREREQUISITES"
.IX Header "PREREQUISITES"
1. You must have the Perl modules \s-1VM::EC2\s0 (v1.21 or later), and
Parse::Apache::ServerStatus installed on the machine you intend to run
the balancer on. The balancer must run on the same machine that
GBrowse is running on. To install these modules, run:
.PP
.Vb 1
\& perl \-MCPAN \-e \*(Aqinstall VM::EC2; install Parse::Apache::ServerStatus\*(Aq
.Ve
.PP
2. You must have an account on Amazon Web Services and must be
familiar with using the \s-1AWS\s0 Console to launch and terminate \s-1EC2\s0
instances. If you run GBrowse on local hardware, then you will need to
provide the script with your access key and secret access key when
launching it. It may be safer to create and use an \s-1IAM\s0 user (Identity
and Access Management) who has more limited privileges. See
\&\s-1CONFIGURATION\s0 below for some suggestions.
.PP
3. GBrowse must be running under Apache.
.PP
4. Apache must be configured to enable the mod_status module and to
allow password-less requests to this module from localhost
(http://httpd.apache.org/docs/2.2/mod/mod_status.html). This is the
recommended configuration:
.PP
ExtendedStatus on
SetHandler server-status
Order deny,allow
Deny from all
Allow from 127.0.0.1 ::1
.PP
5. If you are running GBrowse on local hardware, the local hardware
must be connected to the Internet or have a Virtual Private Cloud
(\s-1VPC\s0) connection to Amazon.
.SH "THE CONFIGURATION FILE"
.IX Header "THE CONFIGURATION FILE"
The balancer requires a configuration file, ordinarily named
aws_balancer.conf and located in the GBrowse configuration directory
(e.g. /etc/gbrowse2). The configuration file has three sections:
.SS "[\s-1LOAD TABLE\s0]"
.IX Subsection "[LOAD TABLE]"
This section describes the number of slave instances to launch for
different load levels. It consists of a three-column space-delimited
table with the following columns:
.PP
.Vb 1
\&
.Ve
.PP
For example, the first few rows of the default table reads:
.PP
.Vb 4
\& 0.1 0 1
\& 0.5 0 2
\& 1.0 1 3
\& 2.0 2 4
.Ve
.PP
This is read as meaning that when the number of requests per second on
the GBrowse server is greater than 0.1 but less than 0.5, run at least
0 slave servers but no more than 1 slave server. When the number of
requests is between 0.5 and 1.0, run between 0 and 2 slave
instances. When the rate is between 1.0 and 2.0, run at least 1 slave
instance, but no more than 3. Load levels below the lowest value on
the table (0.1 in this case) will run no slave servers, while levels
above the highest value on the table (2.0) will launch the minimum and
maximum number of slaves for that load value (between 2 and 4 in this
case).
.PP
The reason for having a range of instance counts for each load range
is to avoid unecessarily launching and killing slaves repeatedly when
the load fluctuates around the boundary. You may wish to tune the
values in this table to maximize the performance of your GBrowse
installation.
.PP
Note that the server load includes both GBrowse requests and all other
requests on the web server. If this is a problem, you may wish to run
GBrowse on a separate Apache port or virtual host.
.SS "[\s-1MASTER\s0]"
.IX Subsection "[MASTER]"
The options in this sections configure the master GBrowse
instance. Three options are recognized:
.IP "external_ip (optional)" 4
.IX Item "external_ip (optional)"
This controls the externally-visible \s-1IP\s0 address of the GBrowse master,
which is needed by the firewall rule for master/slave
communications. This option can usually be left blank: when the master
is running on \s-1EC2,\s0 then the \s-1IP\s0 address is known; when the master is
running on a local machine, the externally-visible \s-1IP\s0 address is
looked up using a web service. It is only in the rare case that this
lookup is incorrect that you will need to configure this option
yourself.
.Sp
The external \s-1IP\s0 that the balancer script finds can be seen in a log
message when verbosity is 2 or higher.
.IP "poll_interval (required)" 4
.IX Item "poll_interval (required)"
This is the interval, in minutes, that the balancer script will
periodically check the Apache load and adjust the number of slave
instances. The suggested value is 0.5 (30s intervals).
.IP "server_status_url (required)" 4
.IX Item "server_status_url (required)"
This is the \s-1URL\s0 to call to fetch the server load from Apache's
server_status module.
.SS "[\s-1SLAVE\s0]"
.IX Subsection "[SLAVE]"
The options in this section apply to the render slaves launched by the
balancer.
.IP "instance_type (required)" 4
.IX Item "instance_type (required)"
This is the \s-1EC2\s0 instance type. Faster instances give better
performance. High-IO instances give the best performance, but cost
more.
.IP "spot_bid (required)" 4
.IX Item "spot_bid (required)"
This is the maximum, in \s-1US\s0 dollars, that you are willing to pay per
hour to run a slave spot instance. Typically you will pay less than
the bid price. If the spot price increases beyond the maximum bid,
then the spot instances will be terminated and the balancer will wait
until the spot price decreases below the maximum bid before launching
additional slaves.
.IP "ports (required)" 4
.IX Item "ports (required)"
This is a space-delimited list of \s-1TCP\s0 port numbers on which the render
slaves should listen for incoming render requests from the
master. Generally it is only necessary to listen on a single port;
multiple ports were supported for performance reasons in earlier
single-threaded versions of the slave.
.IP "region (required for local masters)" 4
.IX Item "region (required for local masters)"
The Amazon region in which to launch slaves. When the master is
running in \s-1EC2,\s0 this is automatically chosen to be the same as the
master's region and can be left blank.
.IP "image_id (required for local masters)" 4
.IX Item "image_id (required for local masters)"
This is the \s-1ID\s0 of the \s-1AMI\s0 that will be used to launch slaves. The
correct value will be filled in when you run the
gbrowse_sync_aws_slave.pl. You can leave this value blank if the
GBrowse master is being run within an \s-1EC2\s0 instance, in which case the
slave will be launched using the same \s-1AMI\s0 that was used to launch the
master.
.IP "data_snapshots (required for local masters)" 4
.IX Item "data_snapshots (required for local masters)"
Before launching the slave, attach \s-1EBS\s0 volumes created from one or
more volume snapshots listed in this option. Multiple snapshots can be
attached by providing a space-delimited list:
.Sp
.Vb 1
\& data_snapshots = snap\-12345 snap\-abcdef
.Ve
.Sp
The gbrowse_sync_aws_slave.pl script will automatically maintain this
option for you.
.IP "availability_zone (optional)" 4
.IX Item "availability_zone (optional)"
This option will force the slave into the named availability zone. If
not specified, an availability zone in the current region will be
chosen at random.
.IP "subnet (optional)" 4
.IX Item "subnet (optional)"
If you are in a \s-1VPC\s0 environment, then this option will force the slave
into the named subnet. Ordinarily the balancer script will launch
slaves into non-VPC instances if the master is running on local
hardware or a non-VPC \s-1EC2\s0 instance. The balancer will launch slaves
into the same \s-1VPC\s0 subnet as the master if the master is running on a
\&\s-1VPC\s0 instance.
.IP "security_group (optional)" 4
.IX Item "security_group (optional)"
This specifies the security group to assign the slaves to. If not
specified, a properly-configured security group will be created as
needed and destroyed when the balancer script exits. If you choose to
manage the security group manually, be sure to configure the firewall
ingress rule to allow access to the slave port(s) (see the \*(L"ports\*(R"
option) from the master's group or \s-1IP\s0 address.
.SH "CONFIGURING AWS CREDENTIALS"
.IX Header "CONFIGURING AWS CREDENTIALS"
To work, the balancer script must be able to make spot instance
requests and to monitor and terminate instances. To perform these
operations the script must have access to the appropriate \s-1AWS\s0
credentials (access key and secret key) on the command line or as
environment variables.
.PP
While the script does its best to shield the credentials from prying
eyes, there is still a chance that the credentials can be intercepted
by another party with login access to the machine that the master runs
on and use the credentials to run up your \s-1AWS\s0 bill. For this reason
some people will prefer to create an \s-1EC2\s0 account or role with limited
access to \s-1AWS\s0 resources.
.IP "1. Your personal \s-1EC2\s0 credentials" 4
.IX Item "1. Your personal EC2 credentials"
You may provide the balancer script with \-\-access_key and \-\-secret_key
command line arguments using your personal \s-1EC2\s0 credentials or set the
environment variables \s-1EC2_ACCESS_KEY\s0 and \s-1EC2_SECRET_KEY.\s0 If not
provided, the script will interactively prompt for one or both of
these values.
.Sp
This is the simplest method, but has the risk that if the credentials
are intercepted by a malicious third party, he or she gains access to
all your \s-1EC2\s0 resources.
.IP "2. The credentials of a restricted \s-1IAM\s0 account" 4
.IX Item "2. The credentials of a restricted IAM account"
You may use the Amazon \s-1AWS\s0 console to create an \s-1IAM\s0 (Identity Access
and Management) user with restricted permissions, and provide that
user's credentials to the script on the command line or with
environment variables. The following \s-1IAM\s0 permission policy is the
minimum needed for the balancer script to work properly:
.Sp
.Vb 10
\& {
\& "Statement": [
\& {
\& "Sid": "BalancerPolicy",
\& "Action": [
\& "ec2:AuthorizeSecurityGroupEgress",
\& "ec2:AuthorizeSecurityGroupIngress",
\& "ec2:CreateSecurityGroup",
\& "ec2:DeleteSecurityGroup",
\& "ec2:DescribeAvailabilityZones",
\& "ec2:DescribeImageAttribute",
\& "ec2:DescribeImages",
\& "ec2:DescribeInstances",
\& "ec2:DescribeInstanceAttribute",
\& "ec2:DescribeInstanceStatus",
\& "ec2:DescribeSecurityGroups",
\& "ec2:DescribeVolumes",
\& "ec2:DescribeSnapshots",
\& "ec2:DescribeSpotInstanceRequests",
\& "ec2:RequestSpotInstances",
\& "ec2:CreateKeyPair",
\& "ec2:DescribeKeyPairs",
\& "ec2:DeleteKeyPair",
\& "ec2:RunInstances",
\& "ec2:TerminateInstances",
\& "ec2:CreateSnapshot",
\& "ec2:CreateVolume",
\& "ec2:CreateTags",
\& "ec2:DeleteTags"
\& ],
\& "Effect": "Allow",
\& "Resource": [
\& "*"
\& ]
\& }
\& ]
\& }
.Ve
.Sp
Note that even with these restrictions, an unauthorized user with
access to the credentials could still launch a large number of spot
instances or terminate bona fide instances. This is just a fundamental
limitation of the granularity of \s-1EC2\s0's permissions system.
.IP "3. Create an \s-1IAM\s0 role" 4
.IX Item "3. Create an IAM role"
If the master is running on an \s-1EC2\s0 instance, then the most convenient
way to pass credentials is by assigning the instance an \s-1IAM\s0 role. The
balancer script can then obtain temporary credentials by making
internal \s-1EC2\s0 calls. The credentials do not need to be provided on the
command line or in environment variables, and are only valid for short
periods of time, limiting the effect of theft.
.Sp
First, create an \s-1IAM\s0 role using the Amazon Console. Select
\&\s-1IAM\-\s0>Roles\->Create New Role, and give the role the name
\&\*(L"GBrowseMaster\*(R" (or whatever you prefer).
.Sp
Next, when prompted for the role type, select \s-1AWS\s0 Service
Roles\->Amazon \s-1EC2.\s0
.Sp
On the Select Role Permissions screen, choose \*(L"Custom Policy\*(R". Give
the policy a name like \*(L"GBrowseBalancer\*(R" and cut and paste into the
Policy Document text field the permission policy listed above in the
instructions for creating a restriced \s-1IAM\s0 account. Be sure to remove
the whitespace before the beginning of the first curly brace, or the
console will complain about an invalid policy.
.Sp
You only need to do this once. After this, whenever you launch an
instance that will run the GBrowse master (typically from a GBrowse
\&\s-1AMI\s0), specify the \*(L"GBrowseMaster\*(R" \s-1IAM\s0 role name. This can be done from
the \s-1AWS\s0 console's instance launch wizard, or by passing the \-p option
to the ec2\-run\-instances command-line tool.
.SH "USING THE INIT SCRIPT"
.IX Header "USING THE INIT SCRIPT"
The gbrowse-aws-balancer init script can be used on Ubuntu and
Debian-based systems to simplify launching the balancer at boot
time. It can be found in /etc/init.d by default, and is called in the
following manner:
.PP
start the service
% sudo /etc/init.d/gbrowse\-aws\-balancer start
.PP
stop the service
% sudo /etc/init.d/gbrowse\-aws\-balancer stop
.PP
stop and restart the service
% sudo /etc/init.d/gbrowse\-aws\-balancer restart
.PP
show the status of the service (running, stopped)
% sudo /etc/init.d/gbrowse\-aws\-balancer status
.PP
The various script options are all set in a single configuration file
named /etc/default/gbrowse\-aws\-balancer. The distribution contents of
this file looks like this:
.PP
.Vb 8
\& DAEMON=/usr/local/bin/gbrowse_aws_balancer.pl
\& USER=www\-data
\& RUNDIR=/var/run/gbrowse
\& LOGDIR=/var/log/gbrowse
\& CONFFILE=/etc/gbrowse2/aws_balancer.conf
\& ACCESS_KEY=YOUR_EC2_ACCESS_KEY_HERE
\& SECRET_KEY=YOUR_EC2_SECRET_KEY_HERE
\& VERBOSITY=3
.Ve
.PP
The variables in this file set the location of the balancer script,
the location of its configuration file, the verbosity to run with, and
where to write the script's process \s-1ID\s0 and log information. In
addition, you can place your (or another authorized user's) \s-1EC2\s0 access
and secret key in this file. Please make sure that this file is only
readable by root.
.SH "DEBUGGING SLAVE PROBLEMS"
.IX Header "DEBUGGING SLAVE PROBLEMS"
If slaves are returning track renderinge errors, then there is likely
an issue with data synchronization. This typically happens when the
data on the master differs from the data on the slave, or path names
are different on the two systems.
.PP
To debug this, launch the script with the \-ssh_key option:
.PP
.Vb 4
\& % gbrowse_aws_balancer.pl \-\-conf /etc/gbrowse2/aws_balancer.conf \e
\& \-\-access_key XYZZY \e
\& \-\-secret_key Plugh \e
\& \-\-ssh_key John_Doe_default
.Ve
.PP
You may then ssh into the slave using the specified ssh key and the
username \*(L"admin\*(R". A useful thing to do is to tail the slave log file:
.PP
.Vb 2
\& ssh \-i .ssh/John_Doe_default admin@54.280.19.203 \e
\& tail \-f /var/log/gbrowse/gbrowse_slave
.Ve
.PP
Replace the \s-1IP\s0 number with the correct \s-1IP\s0 number of one of the running
slaves, which you can find in /etc/gbrowse2/renderfarm.conf.
.SH "THE GBROWSE_SYNC_AWS_SLAVE.PL SCRIPT"
.IX Header "THE GBROWSE_SYNC_AWS_SLAVE.PL SCRIPT"
The gbrowse_sync_aws_script.pl script should be run on the master each
time you add a new database to an existing data source, or if you add
a whole new data source. What it does is to prepare a new Amazon \s-1EBS\s0
snapshot containing a copy of all the data needed for the GBrowse
slave to run. This snapshot is then attached to new slave instances.
.PP
After running, it updates the conf file with the current versions of
the slave \s-1AMI\s0 and the data snapshot.
.PP
.Vb 3
\& % sudo gbrowse_sync_aws_script.pl \-\-conf /etc/gbrowse2/aws_balancer.conf \e
\& \-\-mysql /var/lib/mysql \e
\& \-\-postgres /var/lib/postgresql
.Ve
.PP
The \-\-conf argument is required. The script will create a snapshot of
the appropriate size, mount it on a temporary staging instance, and
rsync a copy of your gbrowse databases directory
(e.g. /var/lib/gbrowse2/databases) to the snapshot. If you have
created mysql or postgres databases, you must also give the paths to
their database file directories, as shown in the example.
.PP
Note that \s-1ALL\s0 your mysql and postgres data files located on the server
will be copied; not just those used for track display.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
The following environment variables are used if the corresponding
command line options are not present:
.PP
.Vb 2
\& EC2_ACCESS_KEY AWS EC2 access key
\& EC2_SECRET_KEY AWS EC2 secret key
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1VM::EC2\s0, VM::EC2::Staging::Manager
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein, lincoln.stein@gmail.com
.PP
Copyright (c) 2012 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.