right_link 5.9.2 → 5.9.5

Sign up to get free protection for your applications and to get access to all the features.
data/INSTALL.rdoc CHANGED
@@ -1,51 +1,27 @@
1
- = DISCLAIMER & WARNING
1
+ = HOW TO GET RIGHTLINK
2
2
 
3
- This guide demonstrates how to build the RightLink gem, install it into any
4
- Ruby interpreter, and integrate it with Linux. This is an advanced procedure
5
- that is intended for people who want to modify or contribute to the RightLink
6
- software itself.
3
+ == Stable Packages
7
4
 
8
- Due to the large number of variables between different OS distributions and
9
- Ruby versions, RightScale cannot support RightLink when it is installed in
10
- this fashion. If your goal is to use RightLink to deploy and manage cloud
11
- servers, then your goals are better accomplished by one of the following
12
- options:
5
+ The latest stable release of RightLink is 5.8.8. You can download the DEB,
6
+ RPM or MSI by visiting the following URL in your Web browser and navigating
7
+ to the appropriate subdir for your OS:
13
8
 
14
- == Use a RightScale-Published Machine Image
9
+ http://mirror.rightscale.com/rightlink/
15
10
 
16
- A RightImage™ is a base machine image, published by RightScale, that can be
17
- used to launch instances in cloud infrastructures. RightImages are unique
18
- from other cloud-based machine images because they are specifically designed
19
- for optimum communication with the RightScale platform. RightImages are
20
- Each of RightScale's published ServerTemplates was tested and published with
21
- one or more RightImages.
11
+ (TODO: provide information on 5.9 stable packages once they are released.)
22
12
 
23
- RightImages are available for several distributions/versions of Linux and
24
- for Windows. They are the best choice for someone who wants a known-good
25
- starting point to build their own ServerTemplates.
13
+ == Beta Packages
26
14
 
27
- Obtain a RightImage:
28
- http://support.rightscale.com/12-Guides/RightScale_101/06-Advanced_Concepts/RightImages
15
+ Beginning with RightLink 5.9, we host our packages in apt, yum, zypp and windows repositories
16
+ for ease of installation.
29
17
 
30
- == Create a RightScale-Enabled Image
31
-
32
- RightScale provides pre-built, supported RightLink packages in several
33
- formats (RPM, DEB, MSI) that are compatible with multiple Linux distributions
34
- and versions.
35
-
36
- Create a RightImage:
37
- http://support.rightscale.com/12-Guides/RightLink/02-RightLink_5.9
38
-
39
- == Install an Early-Access RightLink Package
40
-
41
- For the adventurous, RightScale provides access to nightly builds of RightLink
42
- that are produced from the master branch. These packages undergo automated
43
- regression, but we cannot provide support for nightly builds.
44
-
45
- As of May 2013, we produce nightlies for the following distributions and
18
+ As of November 2013, we produce release candidates builds for the following distributions and
46
19
  releases:
47
20
  * RHEL 6 (also compatible with CentOS 6)
21
+ * SUSE 11
48
22
  * Ubuntu 12.04
23
+ * Ubuntu 13.04
24
+ * Windows Server 2008/2012
49
25
 
50
26
  And the following cloud types:
51
27
  * azure
@@ -53,318 +29,129 @@ And the following cloud types:
53
29
  * ec2
54
30
  * google
55
31
  * openstack
56
- * rackspace (Rackspace Classic)
57
- * rackspace-ng (Rackspace OpenCloud)
32
+ * rackspace (OpenCloud)
58
33
  * softlayer
59
34
 
60
- After installing the RightLink package, you can bundle an image and use
61
- it to create your own MultiCoudImage.
35
+ For all Unix-based systems, RightLink is distributed as a base package plus one
36
+ or more extension packages to provide support for various cloud types. Install
37
+ the extension package that is appropriate for your cloud type, and the OS will
38
+ take care of installing all of its dependencies including the base package.
62
39
 
63
- Alternatively, if you install to an instance that was launched as a server
64
- via the RightScale dashboard, you can reboot the instance to proceed with
65
- running the boot scripts for the associated ServerTemplate.
40
+ For Windows systems, RightLink is distributed as an all-in-one MSI with a
41
+ graphical installer that allows you to choose the cloud type.
66
42
 
67
- === Nightly RPMs
43
+ Regardless of OS, after installing the RightLink package, you can bundle an
44
+ image and use it to create your own MultiCoudImage for use with RightScale.
68
45
 
69
- ==== RedHat
46
+ === RHEL/CentOS 6 installation
70
47
 
71
- For RedHat-based systems, we publish nightly builds to a yum repository.
72
- The repository follows an EPEL-like layout and supports multiple distributions
73
- and releases.
48
+ For RedHat-based systems, we publish and maintain a yum repository. The repository
49
+ follows an EPEL-like layout and supports multiple distributions and releases.
74
50
 
75
- To install nightly RPMs, first create a yum source.
51
+ *Note:* 64-bit is only supported.
76
52
 
77
- cat > /etc/yum.repos.d/RightLink-development.repo <<EOF
53
+ First, import RightScale public key:
54
+
55
+ # Pre-import the rightscale public key
56
+ rpm --import http://s3.amazonaws.com/rightscale_key_pub/rightscale_key.pub
57
+
58
+ Create a yum source:
59
+
60
+ cat > /etc/yum.repos.d/RightLink-staging.repo <<EOF
78
61
  [rightlink]
79
62
  name=RightLink
80
- baseurl=https://rightlink-integration.s3.amazonaws.com/nightly/yum/1/el/$releasever/$basearch/
81
- gpgcheck=0
63
+ baseurl=https://rightlink-staging.s3.amazonaws.com/yum/1/el/6/$basearch/
64
+ gpgcheck=1
65
+ gpgkey=http://s3.amazonaws.com/rightscale_key_pub/rightscale_key.pub
82
66
  EOF
83
67
 
84
- Next install RightLink cloud support package for
85
- the cloud type your instance is running on:
68
+ Next, install RightLink cloud support package for
69
+ the cloud type your instance is running on. Example for Amazon EC2:
86
70
 
87
71
  yum install -y rightlink-cloud-ec2
88
72
 
89
- ==== SUSE
90
-
91
- For SUSE-based systems, we publish nightly builds to a yum repository.
92
- The repository follows an EPEL-like layout and supports multiple distributions
93
- and releases.
73
+ *Note:* Before installing the RightLink package be sure that time of the server is correct. We highly recommend the use of Network Time Protocol (NTP) for synchronizing time on your servers.
94
74
 
95
- To install nightly RPMs, first create a zypper source.
75
+ You can now bundle your image and boot RightScale servers with it.
96
76
 
97
- zypper ar -G -f https://rightlink-integration.s3.amazonaws.com/nightly/yum/1/suse/$releasever/$basearch/
77
+ === SUSE installation
98
78
 
99
- Next install RightLink cloud support package for
100
- the cloud type your instance is running on:
101
-
102
- zypper --non-interactive install rightlink-cloud-ec2
79
+ For SUSE-based systems, we maintain a zypper repository. The repository follows
80
+ an EPEL-like layout and supports multiple distributions and releases.
103
81
 
82
+ *Note:* 64-bit is only supported.
104
83
 
105
- === Nightly DEBs
84
+ First, import RightScale public key:
106
85
 
107
- For Debian-derived systems, we publish nightly builds to an apt repository.
108
- The repository is automatic (supports multiple distributions and releases).
86
+ # Pre-import the rightscale public key
87
+ rpm --import http://s3.amazonaws.com/rightscale_key_pub/rightscale_key.pub
109
88
 
110
- To install nightly DEBs, first create an apt source, ensuring that you specify
111
- the right architecture and release code name. For instance, on an amd64
112
- system that is running Ubuntu 12.04 (precise):
89
+ Create a zypper source:
113
90
 
114
- cat > /etc/apt/sources.list.d/rightlink.sources.list <<EOF
115
- deb [arch=amd64] https://rightlink-integration.s3.amazonaws.com/nightly/apt precise main
116
- deb-src [arch=amd64] https://rightlink-integration.s3.amazonaws.com/nightly/apt precise main
91
+ cat > /etc/zypp/repos.d/RightLink-staging.repo <<EOF
92
+ [rightlink]
93
+ name=RightLink
94
+ baseurl=https://rightlink-staging.s3.amazonaws.com/zypp/1/suse/11/x86_64/
95
+ gpgcheck=1
96
+ gpgkey=http://s3.amazonaws.com/rightscale_key_pub/rightscale_key.pub
117
97
  EOF
118
98
 
119
- Next install RightLink cloud support package for the
120
- cloud type your instance is running on:
121
-
122
- apt-get update
123
- apt-get install rightlink-cloud-ec2
124
-
125
- === Nightly MSIs
126
-
127
- TODO - provide install instructions for nightly MSIs once we begin producing them
128
-
129
- = PREREQUISITES
130
-
131
- RightLink is a Ruby application that runs as a daemon. It depends on the
132
- following system components/packages, which must be installed before you
133
- can proceed with RightLink installation.
134
- * Ruby >= 1.8.7 p371 or better -- older versions have GC issues!
135
- * RubyGems >= 1.8.25
136
- * C/C++ toolchain (needed to install various gems)
137
-
138
- Several auxiliary packages are recommended in order to obtain full RightLink
139
- functionality at runtime:
140
- * git and Subversion clients (facilitates Chef recipe development)
141
- * curl (for download of RightScript attachments)
142
- * dig, sed and perl (used by some cloud-specific config logic)
143
-
144
- == Supported Configurations
145
-
146
- RightLink is regularly tested on the following Linux distributions:
147
- * CentOS - 6.4
148
- * RedHat Enterprise Linux (RHEL) - 6.4
149
- * Ubuntu - 12.04
150
-
151
- It has been known to work on the following with little or no modification:
152
- * Debian
153
- * RedHat Enterprise Linux
154
- * SuSE Linux
155
-
156
- And on the following kinds of cloud:
157
- * Amazon Web Services (AWS)
158
- * Rackspace Cloud Servers
159
- * Eucalyptus
160
- * CloudStack
161
-
162
- Although RightLink is Windows-compatible and is regularly released for
163
- Windows variants, installation and configuration are not yet covered in this
164
- document. For information on the RightLink Windows MSI, see the documentation
165
- page on our {support wiki}[http://support.rightscale.com/12-Guides/Windows_User_Guide]
166
-
167
- == CentOS and RHEL Systems
168
-
169
- Install the C toolchain and related libraries, plus some additional libs
170
- required for RightLink,
171
-
172
- yum install -y autoconf bison byacc flex gcc ncurses db4-devel glibc-devel libarchive-devel openssl-devel ncurses-devel
173
-
174
- Older releases of CentOS (before 6.x) ship with a Ruby VM that is too old. To run RightLink, you
175
- can build Ruby from source and install it under a different prefix such as /opt/rightscale/sandbox.
176
-
177
- == Ubuntu Systems
178
-
179
- Install the C toolchain and related libraries, plus some additional libs
180
- required for RightLink.
181
-
182
- apt-get update
183
- # may need libreadline5 (not 6), on older systems. Ditto with libreadline5-dev
184
- apt-get install -y libssl-dev libarchive-dev libreadline-dev autoconf flex bison
185
- # apt-get install -y build-essential gcc g++ bison openssl libreadline6 zlib1g vim autoconf libxml2 libffi
186
- # apt-get install -y libssl-dev libreadline-dev zlib1g-dev libyaml-dev libffi-dev libxml2-dev
187
- # apt-get install -y git-core perl sed curl dnsutils
188
-
189
- Newer releases of Ubuntu (11.04 and above) ship with a Ruby 1.9 VM that is too new. To run RightLink, you
190
- can build Ruby from source and install it under a different prefix such as /opt/rightscale/sandbox.
99
+ Next, install RightLink cloud support package for
100
+ the cloud type your instance is running on. Example for Amazon EC2:
191
101
 
192
- = PRE-INSTALL CUSTOMIZATION
193
-
194
- == Feature Control Customization
195
-
196
- Before installing RightLink (either as a package or from sources), you can
197
- selectively disable certain features that may not be compatible with your
198
- deployment environment.
199
-
200
- Feature control is accomplished by creating a special YAML file prior to
201
- installing the package or running any RightLink init script or program
202
- logic. The YAML file contains some boolean flags that affect the behavior
203
- of the init scripts and the agent at runtime.
204
-
205
- The following features can all be disabled:
206
- * Managed login (aka Server Login Control)
207
- * Frozen OS package repositories
208
- * Automatic MOTD update on state transitions
209
-
210
- To disable one or more of these features, create the following file:
211
-
212
- /etc/rightscale.d/right_link/features.yml
213
-
214
- And populate the file thusly, supplying true/false for each feature
215
- as appropriate.
216
-
217
- motd:
218
- update: false
219
- package_repositories:
220
- freeze: false
221
- managed_login:
222
- enable: false
223
-
224
- All features are assumed to be enabled by default unless this file exists
225
- and the associated feature is marked as disabled. Therefore, you can omit
226
- sections for features that should remain enabled.
227
-
228
- = INSTALLATION
229
-
230
- == One-Time Setup
231
-
232
- If you are packaging RightLink, run these commands as a post-install step
233
- for your package. If you are bundling a cloud image, run these commands
234
- _before_ bundling.
235
-
236
- git clone git://github.com/rightscale/right_link.git
237
- cd right_link
238
- bundle install
239
- bundle exec rake gem
240
- gem install pkg/right_link-5.9.0.gem
241
-  
242
- The RubyGems installer will create a number of executable binaries in
243
- your RubyGems bindir. These binaries control the operation of RightLink
244
- and allow you and your scripts to interact with the management agent.
245
-
246
- On Unix systems, the CLI binaries are normally created in /usr/bin, but
247
- it depends on how your Ruby interpreter was installed and packaged. You
248
- can determine the location of your RubyGems bindir by running:
249
-
250
- gem env
251
-
252
- By convention, most RightLink tools begin with the prefix "rs_" e.g.
253
- rs_tag or rs_run_recipe.
254
-
255
- = INTEGRATING WITH THE SYSTEM
256
-
257
- == Multi-Cloud Support
258
-
259
- export RS_CLOUD=ec2 # or another cloud type, see below...
260
- mkdir -p /etc/rightscale.d
261
- echo "$RS_CLOUD" > /etc/rightscale.d/cloud
262
-
263
- RightLink supports many virtualization engines, cloud APIs and other facets
264
- of cloud technology. Due to lack of standardization, there is no reliable
265
- way for RightLink to auto-detect the cloud type in which it is running.
266
-
267
- We have taken the pragmatic approach and require the user to give RightLink a
268
- hint about its runtime environment. RightLink must know its cloud type in
269
- order to retrieve launch settings and runtime metadata that are crucial to
270
- successful operation.
271
-
272
- In the commands below, we refer to an environment variable RS_CLOUD. You
273
- should set RS_CLOUD to the cloud type under which RightLink is running, before
274
- running any of the commands below. RS_CLOUD is your "hint" to RightLink.
275
-
276
- RightLink knows about the following values of RS_CLOUD:
277
- * ec2
278
- * rackspace
279
- * rackspace-ng
280
- * eucalyptus
281
- * cloudstack
282
- * openstack
283
- * softlayer
284
-
285
- == On-Boot Commands
102
+ zypper --non-interactive install rightlink-cloud-ec2
286
103
 
287
- Under Linux these are accomplished with init scripts. Under Windows, a system
288
- service spawns the agent process and monitors its health.
104
+ *Note:* Before installing the RightLink package be sure that time of the server is correct. We highly recommend the use of Network Time Protocol (NTP) for synchronizing time on your servers.
289
105
 
290
- CAUTION: if your instance is attached to the RightScale dashboard, running
291
- the commands below will cause it to begin running boot scripts! This is not
292
- harmful, but if your intent is to bundle a "pristine" image, you probably
293
- want to put the following commands into an init script and test by bundling
294
- and relaunching.
106
+ You can now bundle your image and boot RightScale servers with it.
295
107
 
296
- #The commands below use relative paths for readability
297
- cd /opt/rightscale
298
-  
299
- # Fetch metadata from cloud and make it available in the shell environment
300
- bin/cloud --name $RS_CLOUD --action bootstrap > /dev/null
301
- . /var/spool/cloud/user-data.sh
302
-  
303
- === Determine Boot State
108
+ === Ubuntu installation
304
109
 
305
- # TODO - check_for_rightscale
110
+ For Debian-derived systems, maintain an automatic, pooled apt repository.
306
111
 
307
- # TODO - rightboot init script (detect reboot & tweak state)
112
+ *Note:* 64-bit is only supported.
308
113
 
309
- # TODO - check_boot_state, update_boot_state 
114
+ First, import RightScale public key:
310
115
 
311
- === Run Fix-It Tasks
116
+ # Import RightScale public key
117
+ curl http://s3.amazonaws.com/rightscale_key_pub/rightscale_key.pub | apt-key add -
312
118
 
313
- # TODO - UNDOCUMENTED - bin/system --action ssh
314
- # TODO - UNDOCUMENTED - bin/system --action hostname
315
- # TODO - UNDOCUMENTED - bin/system --action proxy
119
+ Create an apt source, ensuring that you specify the right architecture
120
+ and release code name. For instance, on an amd64 system that is running:
316
121
 
317
- === Configure RightLink Agent
318
-  
319
- bin/enroll --root-dir /var/lib/rightscale/right_link --url $RS_RN_URL --host $RS_RN_HOST --id $RS_RN_ID --token $RS_RN_AUTH
320
- bin/deploy
321
-  
322
- === Launch RightLink Agent
122
+ # Ubuntu 12.04 (precise)
123
+ cat > /etc/apt/sources.list.d/rightlink.sources.list <<EOF
124
+ deb [arch=amd64] https://rightlink-staging.s3.amazonaws.com/apt precise main
125
+ deb-src [arch=amd64] https://rightlink-staging.s3.amazonaws.com/apt precise main
126
+ EOF
323
127
 
324
- # Start the RightLink agent
325
- bin/rnac --start instance
128
+ # Ubuntu 13.04 (raring)
129
+ cat > /etc/apt/sources.list.d/rightlink.sources.list <<EOF
130
+ deb [arch=amd64] https://rightlink-staging.s3.amazonaws.com/apt raring main
131
+ deb-src [arch=amd64] https://rightlink-staging.s3.amazonaws.com/apt raring main
132
+ EOF
326
133
 
327
- # Start the agent watchdog process
328
- bin/rchk --start
329
134
 
330
- At this point, your instance should be booting and sending audit entries back to the RightScale dashboard.
331
- Navigate to this server and verify that it's booting cleanly.
135
+ Next, install RightLink cloud support package for the cloud type your instance is running on. Example for Amazon EC2:
332
136
 
333
- == On-Shutdown Commands
137
+ apt-get update
138
+ apt-get install rightlink-cloud-ec2
334
139
 
335
- When the system is terminating, you should allow RightLink to run its decommission scripts.
140
+ *Note:* Before installing the RightLink package be sure that time of the server is correct. We highly recommend the use of Network Time Protocol (NTP) for synchronizing time on your servers.
336
141
 
337
- #The commands below use relative paths for readability
338
- cd /opt/rightscale
339
-  
340
- bin/rnac --decommission
142
+ You can now bundle your image and boot RightScale servers with it.
341
143
 
342
- == Filesystem Locations
144
+ === Windows Installation
343
145
 
344
- === Linux Systems
146
+ For Windows systems, we publish MSIs to Amazon S3; find the file that is suitable for your CPU
147
+ architecture and download it with your Web browser:
345
148
 
346
- /etc/rightscale.d | Static configuration, incl. "hints" for init scripts
347
- /etc/rightscale.d/right_link | Static files that customize RightLink behavior
348
- /var/spool/cloud | Cloud-provided metadata & user-data
349
- /var/lib/rightscale/right_agent | Persistent config files generated at startup
350
- /var/lib/rightscale/right_link | Persistent RightLink agent state
351
- /var/run | Transient agent state, e.g. pid files
352
- /var/cache | Cookbooks, attachments, temp files
353
- /usr/bin | Public CLI: rs_tag, rs_debug, ...
354
- /opt/rightscale/bin | Private CLI: rnac, rad, cook, ...
355
- /opt/rightscale/sandbox | Private sandbox (Ruby, RubyGems, ...)
149
+ https://rightlink-staging.s3.amazonaws.com/windows/RightLink-5.9.3-2-i386.msi
356
150
 
357
- === Windows Systems
151
+ https://rightlink-staging.s3.amazonaws.com/windows/RightLink-5.9.3-2-x64.msi
358
152
 
359
- Data files -- paths are relative to %COMMON_APPDATA%\RightScale
360
153
 
361
- rightscale.d | Static "hints" for system services
362
- spool\cloud | Cloud-provided metadata & user-data (.sh, .rb, raw formats)
363
- RightAgent | Persistent config files generated at startup
364
- right_link | Persistent RightLink agent state
365
- cache | Cookbooks, attachments, temp files
154
+ *Note:* Before installing the RightLink package be sure that time of the server is correct. We highly recommend the use of Network Time Protocol (NTP) for synchronizing time on your servers.
366
155
 
367
- Program logic -- paths are relative to %ProgramFiles(x86)%
156
+ Next, run the installer to complete installation. Do not forget to choose the appropriate cloud type during installing.
368
157
 
369
- RightScale\RightLink | Application logic & support files
370
- RightScale\sandbox | Private sandbox (Ruby, RubyGems, ...)