forked from pkolano/ballast
-
Notifications
You must be signed in to change notification settings - Fork 0
/
INSTALL
187 lines (124 loc) · 6.3 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
Ballast Installation and Configuration
======================================
1. Deployments
A Ballast deployment consists of:
o A Ballast agent on each host to be load balanced to collect
load information
o A Ballast server on one or more hosts to process load
information and select hosts for clients based on configured
policies
o A Ballast client on each host that will invoke the balancer to
request balancing decisions from the server
Any number of load balancing aliases can be defined for any number
of hosts. For example, an alias "foo" might be used to invoke the
load balancer across hosts {foo1,foo2,bar1,bar2}. Namely, when the
user invokes "ssh foo", Ballast will dynamically select one of
{foo1,foo2,bar1,bar2} according to the configured load balancing
policy for alias foo and connect to that system (e.g. foo2) as if
the user had directly invoked "ssh foo2".
2. Prerequisites
2.1. Host keys
All SSH host keys across the balanced systems for a particular
alias must be identical. Otherwise, internal SSH host key
checks will fail when the stored known host key for the alias
does not match the host key offered by the selected host. See
"man sshd" and "man sshd_config" for details on configuring
host keys.
If multiple balancing aliases are defined, the host keys may
differ between the hosts of different aliases.
2.2. Ballast agent
o Perl >= 5.8
2.3. Ballast client
2.3.1. Perl client
o Perl >= 5.6
2.3.2. C client
o C (compilation only)
o Make (compilation only)
o Netcat (or equivalent such as tcpconnect from tcputils)
2.4. Ballast server
o Perl >= 5.8
3. Build
3.1. Ballast C client (optional)
The Ballast client comes in two flavors: Perl and C. If Perl is
installed and available to users, the Perl version is
recommended. The C version is intended for systems that either
don't have Perl installed or for which it is not generally
accessible to users (e.g. bastion hosts with a restricted
chroot environment).
To build the C client, run:
make
The Makefile assumes gcc and may need to be modified if an
alternate compiler is installed.
3.2. Debian package (optional)
An optional Debian package can be built at the top of the source
directory using:
dpkg-buildpackage -B
After the command completes, a .deb file should exist in the
parent directory. The file name will vary depending on the
Ballast version, but will be in the general form
"ballast_VERSION-REL_ARCH.deb".
4. Installation
4.1. Debian package installation
If the Debian package has been built, the package file can be
installed to prefix /usr using:
dpkg -i ballast*.deb
Note that this installs the Perl client. The C client must be
installed manually, if desired.
4.2. Make installation
If the "make" command is available on the system, the different
components can be installed via make. The installation prefix
can be changed from the default "/usr/local" to a different
location by adjusting the value of the "PREFIX" variable in
"Makefile".
To install all components (except for C client), run:
make install
For component X in {agent, client, c_client, server}, X can be
installed using:
make install_X
For example, the install the standard Perl client, run:
make install_client
After either the agent or server is installed on a systemd
host, the following must be run:
systemctl daemon-reload
4.3. Manual installation
Files can be installed manually as given below. Note that
/usr/local is used as the default install prefix in all
examples, but can be changed to any other desired location.
The location of the config file can also be changed from
/etc/ballastrc, but then requires that the agent, client, and/or
server be invoked with additional parameters "-c
/path/to/config/file".
After either the agent or server is installed on a systemd
host, the following must be run:
systemctl daemon-reload
4.3.1. Ballast agent installation
On each host to be load balanced:
install -m 755 perl/ballast-agent /usr/local/sbin/
install -m 644 etc/ballastrc /etc/
# To install relevant documentation:
install -m 644 doc/ballast-agent.1 /usr/local/man/man1/
install -m 644 doc/ballastrc.5 /usr/local/man/man5/
# If the Ballast agent will be run via systemd timer:
install -m 644 etc/systemd/system/ballast-agent.service /etc/systemd/system/
install -m 644 etc/systemd/system/ballast-agent.timer /etc/systemd/system/
4.3.2. Ballast client installation
On each host that will invoke the balancer:
# change to c/ballast if using the C client
install -m 755 perl/ballast /usr/local/bin/
install -m 644 etc/ballastrc /etc/
# To install relevant documentation:
install -m 644 doc/ballast.1 /usr/local/man/man1/
install -m 644 doc/ballastrc.5 /usr/local/man/man5/
4.3.3. Ballast server installation
On one or more hosts:
install -m 755 perl/ballastd /usr/local/sbin/
install -m 644 etc/ballastrc /etc/
# To install relevant documentation:
install -m 644 doc/ballastd.1 /usr/local/man/man1/
install -m 644 doc/ballastrc.5 /usr/local/man/man5/
# If the Ballast server will be run as a systemd service:
install -m 644 etc/systemd/system/ballast.service /etc/systemd/system/
install -m 644 etc/systemd/system/ballast.socket /etc/systemd/system/
5. Configuration and Usage
See individual man page entries for ballast(1), ballastd(1),
ballast-agent(1), and ballastrc(5).