Module: ScoutAgent::Planned

Defined in:
lib/scout_agent/plan.rb

Overview

These extra methods are mixed into the OpenStruct stored in ScoutAgent::Plan. They add support for defaults, some interface improvements, support for configuration files and command-line switches, plus validation.

To see the options stored in the plan and their current values, use the following command:

scout_agent config

Instance Method Summary collapse

Instance Method Details

#agent_url ⇒ Object

Returns the full URL for check-ins by this agent. This is the server_url plus the agent path and the key specific to this agent.



392
393
394
 
# File 'lib/scout_agent/plan.rb', line 392

def agent_url
  URI.join(server_url, "clients/#{agent_key}")
end

#build_db_dir(group_id) ⇒ Object

Builds the database directory for this agent, owned by group_id but with full privileges for all.



349
350
351
 
# File 'lib/scout_agent/plan.rb', line 349

def build_db_dir(group_id)
  build_dir(:db_dir, 0777, group_id)
end

#build_log_dir(group_id) ⇒ Object

Builds the log directory for this agent, owned by group_id but with full privileges for all.



365
366
367
 
# File 'lib/scout_agent/plan.rb', line 365

def build_log_dir(group_id)
  build_dir(:log_dir, 0777, group_id)
end

#build_pid_dir(group_id) ⇒ Object

Builds the PID file directory for this agent, owned by group_id but readable by all.



357
358
359
 
# File 'lib/scout_agent/plan.rb', line 357

def build_pid_dir(group_id)
  build_dir(:pid_dir, 0775, group_id)
end

#config_file ⇒ Object

The full path to the loaded configuration file, prefixed by prefix_path and the os_config_path. By default, this file is named after the agent.



326
327
328
 
# File 'lib/scout_agent/plan.rb', line 326

def config_file
  os_config_path + (super || "#{ScoutAgent.agent_name}.rb")
end

#db_dir ⇒ Object

The database path for this agent, using prefix_path() and os_db_path().



331
332
333
 
# File 'lib/scout_agent/plan.rb', line 331

def db_dir
  os_db_path + (super || ScoutAgent.agent_name)
end

#defaults ⇒ Object

The default configuration for this agent.



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/scout_agent/plan.rb', line 22

def defaults
  [ [:server_url,         "https://scoutapp.com"],
    [:proxy_url,          nil],
    [:run_as_daemon,      true],
    [:logging_level,      "INFO"],
    [:enable_xmpp,        false],
    [:test_mode,          false],

    [:periodic_snapshots, true],
    [:xmpp_trusted,       %w[scout@*]],
    [:user_choices,       %w[daemon nobody]],
    [:group_choices,      %w[daemon nogroup]],
    [:prefix_path,        "/"],
    [:os_config_path,     "etc"],
    [:os_db_path,         "var/db"],
    [:os_pid_path,        "var/run"],
    [:os_log_path,        "var/log"],
    [:config_file,        nil],
    [:db_dir,             nil],
    [:pid_dir,            nil],
    [:log_dir,            nil] ]
end

#enable_xmpp? ⇒ Boolean

Provide a more natural interface for ScoutAgent::Plan#enable_xmpp.

Returns:

  • (Boolean) 


77
78
79
 
# File 'lib/scout_agent/plan.rb', line 77

def enable_xmpp?
  enable_xmpp
end

#log_dir ⇒ Object

The log path for this agent, using prefix_path() and os_log_path().



341
342
343
 
# File 'lib/scout_agent/plan.rb', line 341

def log_dir
  os_log_path + (super || ScoutAgent.agent_name)
end

#os_config_path ⇒ Object

The configuarion path for your operation system, using prefix_path().



303
304
305
 
# File 'lib/scout_agent/plan.rb', line 303

def os_config_path
  prefix_path + super
end

#os_db_path ⇒ Object

The database path for your operation system, using prefix_path().



308
309
310
 
# File 'lib/scout_agent/plan.rb', line 308

def os_db_path
  prefix_path + super
end

#os_log_path ⇒ Object

The log path for your operation system, using prefix_path().



318
319
320
 
# File 'lib/scout_agent/plan.rb', line 318

def os_log_path
  prefix_path + super
end

#os_pid_path ⇒ Object

The PID file path for your operation system, using prefix_path().



313
314
315
 
# File 'lib/scout_agent/plan.rb', line 313

def os_pid_path
  prefix_path + super
end

#periodic_snapshots? ⇒ Boolean

Provide a more natural interface for ScoutAgent::Plan#periodic_snapshots.

Returns:

  • (Boolean) 


82
83
84
 
# File 'lib/scout_agent/plan.rb', line 82

def periodic_snapshots?
  periodic_snapshots
end

#pid_dir ⇒ Object

The PID file path for this agent, using prefix_path() and os_pid_path().



336
337
338
 
# File 'lib/scout_agent/plan.rb', line 336

def pid_dir
  os_pid_path + (super || ScoutAgent.agent_name)
end

#prefix_path ⇒ Object

A prefix used in all configuration paths.



298
299
300
 
# File 'lib/scout_agent/plan.rb', line 298

def prefix_path
  Pathname.new(super)
end

#prepare_global_database(name) ⇒ Object

This method is used to prepare a database that can be accessed by any process. The database is first loaded by name. Then the permissions on that database are changed to allow all processes to read and write to the created database.



406
407
408
409
410
411
412
 
# File 'lib/scout_agent/plan.rb', line 406

def prepare_global_database(name)
  db = Database.load(name) or return false
  db.path.chmod(0777)
  true
rescue Errno::EPERM  # don't have permission
  false
end

#present? ⇒ Boolean

Returns true if all needed configuration paths exist.

Returns:

  • (Boolean) 


419
420
421
422
 
# File 'lib/scout_agent/plan.rb', line 419

def present?
  %w[config_file db_dir log_dir].all? { |path| send(path).exist? } and
  %w[queue snapshots].all?            { |db|   Database.path(db).exist? }
end

#run_as_daemon? ⇒ Boolean

Provide a more natural interface for ScoutAgent::Plan#run_as_daemon.

Returns:

  • (Boolean) 


67
68
69
 
# File 'lib/scout_agent/plan.rb', line 67

def run_as_daemon?
  run_as_daemon
end

#set_defaults ⇒ Object Also known as: reset_defaults

This method is used to set or reset the default configuration. It returns self to support method chaining.



49
50
51
52
53
54
 
# File 'lib/scout_agent/plan.rb', line 49

def set_defaults
  defaults.each do |name, value|
    send("#{name}=", value)
  end
  self  # for chaining
end

#test_mode? ⇒ Boolean

Provide a more natural interface for ScoutAgent::Plan#test_mode.

Returns:

  • (Boolean) 


72
73
74
 
# File 'lib/scout_agent/plan.rb', line 72

def test_mode?
  test_mode
end

#update_from_config_file(path = config_file) ⇒ Object

This method loads configuration settings from a plain Ruby file.



91
92
93
94
95
96
97
 
# File 'lib/scout_agent/plan.rb', line 91

def update_from_config_file(path = config_file)
  eval <<-END_UPDATE
  config = self
  #{File.read(path)}
  config
  END_UPDATE
end

#update_from_switches(hash) ⇒ Object Also known as: update_from_hash

This method allows mass update through a hash of settings.



286
287
288
289
290
 
# File 'lib/scout_agent/plan.rb', line 286

def update_from_switches(hash)
  hash.each do |name, value|
    send("#{name}=", value)
  end
end

#valid? ⇒ Boolean

Returns true if present? and all needed configuration paths have proper permisions as far as this current run is concerned.

Returns:

  • (Boolean) 


428
429
430
431
432
433
434
435
 
# File 'lib/scout_agent/plan.rb', line 428

def valid?
  present?                                                            and
  %w[config_file db_dir log_dir].all? { |path| send(path).readable? } and
  %w[db_dir log_dir].all?             { |path| send(path).writable? } and
  %w[queue snapshots].map             { |db|   Database.path(db) }.
                      all?            { |path| path.readable? and
                                               path.writable? }
end

#write_default_config_file ⇒ Object

This method places the current configuration into a standard configuration file. This makes it easy for users to edit this file and modify all future runs of the agent.



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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/scout_agent/plan.rb', line 104

def write_default_config_file
  config_file.dirname.mkpath
  config_file.open(File::CREAT | File::EXCL | File::WRONLY) do |pid|
    pid.puts <<-END_DEFAULT_CONFIG.trim
    #!/usr/bin/env ruby -wKU
    # encoding: UTF-8
    
    # #{ScoutAgent.proper_agent_name} v#{ScoutAgent::VERSION}

    # 
    # This file configures #{ScoutAgent.proper_agent_name}.  The settings in
    # here should get you started.  You can tweak these as the need arises.
    # 
    # Any Ruby code you would like run at start-up is a valid addition
    # to this file.
    # 
    
    ####################
    ### Basic Config ###
    ####################

    # The key below is how the server identifies this machine:
    config.agent_key = #{agent_key.inspect}
    
    # The following is the URL used to reach the server:
    config.server_url = #{server_url.inspect}
    # 
    # Set the following if your HTTP requests need to go through a proxy.
    # All non-XMPP requests between the agent and the server will go through
    # this URL.
    # 
    config.proxy_url = #{proxy_url.inspect}
    
    # 
    # When the following is true, the agent will disconnect from the
    # terminal that launches it and run in the background.  You can
    # switch this to false to have the program stay connected and log
    # to STDOUT.  This can be handy when debugging issues.
    # 
    # You can set this option to false for a single run with the
    # command-line switch --no-daemon.
    # 
    config.run_as_daemon = #{run_as_daemon.inspect}
    
    # 
    # The following sets your logging level for the agent.  This setting can
    # be one of "DEBUG", "INFO", "WARN", "ERROR", or "FATAL".  Messages
    # below the seleted level will not be written to the logs.  "DEBUG" is
    # intended for the developers as it includes some very low level data,
    # "INFO" (the default) is good general purpose logging that will what
    # the agent does as it works, and "WARN" is a good choice if you want
    # to minimize log space taken but still see problems.  Logs are rotated 
    # daily and deleted after seven days though, so you shouldn't need to
    # worry about the agent filling up your hard drive.
    #
    # This agent includes a command to upload logs to our server.  This is
    # never done automatically or without your permission, but it can help
    # us troubleshoot issues on your box.  We will give you the proper
    # command for this during a support request if we think it would help.
    # Rest assured that agent logs do not contain sensative data.
    # 
    config.logging_level = #{logging_level.inspect}
    
    # 
    # The XMPP features of the agent are used to allow the server to remain
    # in contact.  The server can use this to send some simple commands to
    # the agent as you interact with the Web interface.  The server may also
    # use this to monitor when the agent is online.
    # 
    # This feature takes some extra memory due to maintaining the XMPP
    # connection.  Set the following to false if you don't need this
    # interactivity and you would prefer to see the agent run with a smaller
    # footprint.
    # 
    config.enable_xmpp = #{enable_xmpp.inspect}
    
    #####################
    ### Expert Config ###
    #####################
    
    # 
    # The following setting causes the agent to attempt taking regular
    # snapshots of the system.  An attempt is made before each check-in, but
    # command intervals will usually only allow them to be run after a few
    # check-ins.
    #
    # Change this setting to false if you would prefer to manage when
    # snapshots are taken manually using the shell command or the API.
    # 
    config.periodic_snapshots = #{periodic_snapshots.inspect}
    
    # 
    # The following list of Jabber users are trusted to send the agent
    # commands.  Only commands from from a user matching one of the names
    # in this list will be executed.
    # 
    # The names in this list must match at the beginning of the user's name
    # and stop at a word boundary.  Thus, all of the following would match
    # the user "[email protected]":
    # 
    #   scout
    #   scout@scoutapp
    #   [email protected]
    # 
    # Note that the first name would match a "scout" user from any domain
    # and the second would match a ".com", ".net", ".org", or whatever, but
    # the third requires a full match.  However, "scout@scout" will not
    # match "[email protected]" since it doesn't end at a boundary.
    # 
    # There's also a special case where any name ending in "@*" is modified
    # to have the "*" replaced with the host name from config.server_url.
    #
    # Feel free to add Jabber (XMPP) users to the list so they too can
    # monitor and command the agent from their IM client.
    # 
    config.xmpp_trusted = %w[#{xmpp_trusted.join(" ")}]
    
    # 
    # The agent will try to use standard Unix locations to store its
    # data, but you are free to adjust these paths as needed.
    # 
    # The prefix is prepended to all other paths, so you can change
    # just that to move all agent related storage.  The other three
    # paths are specific locations where resources will be stored,
    # so you can adjust those separately if needed.
    # 
    # Note:  to have the prefix effect the location of this file or
    # to set your OS's configuration path, you will need to use 
    # command-line switches (--prefix and --os-config-path respectively).
    # It wouldn't help to have those settings in this file as they are
    # needed before this file is loaded.
    # 
    config.prefix_path = #{prefix_path.to_s.inspect}
    
    config.os_db_path  = #{os_db_path.
                           relative_path_from(prefix_path).to_s.inspect}
    config.os_pid_path = #{os_pid_path.
                           relative_path_from(prefix_path).to_s.inspect}
    config.os_log_path = #{os_log_path.
                              relative_path_from(prefix_path).to_s.inspect}
    
    #
    # The agent must be started with super user privileges so it can
    # prepare the environment for a long run.  However, it will abandon
    # these privileges once setup is complete to better protect your
    # security.
    # 
    # The following are the list of users and groups the agent will
    # try to switch to.  Choices are tried from left to right, so by
    # default the "daemon" user is used but the agent will try
    # "nobody" if daemon is not available.  These are standard users
    # and groups for long running processes on Unix.
    # 
    # If you wish to improve security even more, we recommend creating
    # a user and group called "#{ScoutAgent.agent_name}" and replacing these 
    # defaults with what you created.  This puts you in full control
    # of what the agent will have access to on your system and makes
    # it easier to track what the agent is doing.
    # 
    config.user_choices  = %w[#{user_choices.join(" ")}]
    config.group_choices = %w[#{group_choices.join(" ")}]
    
    ############################
    ### Your Personal Config ###
    ############################

    # Add any additional Ruby code you need to run at start-up below...
    END_DEFAULT_CONFIG
  end
  config_file.chmod(0755)
  true
rescue Errno::EEXIST  # file already exists
  false
rescue Errno::EACCES  # don't have permission
  false
end