Module: NginxStage::Configuration

Included in:
NginxStage
Defined in:
lib/nginx_stage/configuration.rb

Overview

An object that stores the configuration options to control NginxStage’s behavior.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#app_config_path(env:, owner:, name:) ⇒ String

Path to generated NGINX app config

Examples:

Dev app owned by Bob

app_config_path(env: :dev, owner: 'bob', name: 'rails1')
#=> "/var/lib/nginx/config/apps/dev/bob/rails1.conf"

User app owned by Dan

app_config_path(env: :usr, owner: 'dan', name: 'fillsim')
#=> "/var/lib/nginx/config/apps/usr/dan/fillsim.conf"

Parameters:

  • env (Symbol) —

    environment the app is run under

  • owner (String) —

    the owner of the app

  • name (String) —

    the name of the app

Returns:

  • (String) —

    the path to the nginx app config on the local filesystem



196
197
198
 
# File 'lib/nginx_stage/configuration.rb', line 196

def app_config_path(env:, owner:, name:)
  File.expand_path @app_config_path[env] % {env: env, owner: owner, name: name}
end

#app_passenger_env(env:, owner:, name:) ⇒ String

The passenger environment used for the given app environment

Examples:

Dev app owned by Bob

app_passenger_env(env: :dev, owner: 'bob', name: 'rails1')
#=> "development"

User app owned by Dan

app_passenger_env(env: :usr, owner: 'dan', name: 'fillsim')
#=> "production"

Parameters:

  • env (Symbol) —

    environment the app is run under

  • owner (String) —

    the owner of the app

  • name (String) —

    the name of the app

Returns:

  • (String) —

    the passenger environment to run app with in PUN



286
287
288
 
# File 'lib/nginx_stage/configuration.rb', line 286

def app_passenger_env(env:, owner:, name:)
  @app_passenger_env.fetch(env, "production")
end

#app_request_regex ⇒ Hash

Regular expression used to distinguish the environment from a request URI and from there distinguish the app owner and app name

Returns:

  • (Hash) —

    hash of regular expressions used to determine app from app namespace for given environment

See Also:



249
250
251
 
# File 'lib/nginx_stage/configuration.rb', line 249

def app_request_regex
  @app_request_regex.each_with_object({}) { |(k, v), h| h[k] = ::Regexp.new v }
end

#app_request_uri(env:, owner:, name:) ⇒ String

The URI used to access the app from the browser, not including any base-uri

Examples:

URI for dev app owned by Bob

app_request_uri(env: :dev, owner: 'bob', name: 'rails1')
#=> "/dev/rails1"

URI for user app owned by Dan

app_request_uri(env: :dev, owner: 'dan', name: 'fillsim')
#=> "/usr/dan/fillsim"

Parameters:

  • env (Symbol) —

    environment the app is run under

  • owner (String) —

    the owner of the app

  • name (String) —

    the name of the app

Returns:

  • (String) —

    the URI used to access a given app

Raises:



236
237
238
239
240
 
# File 'lib/nginx_stage/configuration.rb', line 236

def app_request_uri(env:, owner:, name:)
  @app_request_uri.fetch(env) do
    raise InvalidRequest, "invalid request environment: #{env}"
  end % {env: env, owner: owner, name: name}
end

#app_root(env:, owner:, name:) ⇒ String

Path to the app root on the local filesystem

Examples:

App root for dev app owned by Bob

app_root(env: :dev, owner: 'bob', name: 'rails1')
#=> "~bob/ondemand/dev/rails1"

App root for user app owned by Dan

app_root(env: :usr, owner: 'dan', name: 'fillsim')
#=> "/var/www/ood/apps/usr/dan/gateway/fillsim"

Parameters:

  • env (Symbol) —

    environment the app is run under

  • owner (String) —

    the owner of the app

  • name (String) —

    the name of the app

Returns:

  • (String) —

    the path to the app root on the local filesystem

Raises:



214
215
216
217
218
219
220
 
# File 'lib/nginx_stage/configuration.rb', line 214

def app_root(env:, owner:, name:)
  File.expand_path(
    @app_root.fetch(env) do
      raise InvalidRequest, "invalid request environment: #{env}"
    end % {env: env, owner: owner, name: name, portal: portal}
  )
end

#app_token(env:, owner:, name:) ⇒ String

Token used to identify a given app from the other apps

Examples:

app token for dev app owned by Bob

app_token(env: :dev, owner: 'bob', name: 'rails1')
#=> "dev/bob/rails1"

app token for user app owned by Dan

app_request_uri(env: :dev, owner: 'dan', name: 'fillsim')
#=> "usr/dan/fillsim"

Parameters:

  • env (Symbol) —

    environment the app is run under

  • owner (String) —

    the owner of the app

  • name (String) —

    the name of the app

Returns:

  • (String) —

    the token identifying the app

Raises:



267
268
269
270
271
 
# File 'lib/nginx_stage/configuration.rb', line 267

def app_token(env:, owner:, name:)
  @app_token.fetch(env) do
    raise InvalidRequest, "invalid request environment: #{env}"
  end % {env: env, owner: owner, name: name}
end

#disabled_shell ⇒ String

Restrict starting up per-user NGINX process as user with this shell. NB: This only affects the pun command, you are still able to

start or stop the PUN using other commands (e.g., <tt>nginx</tt>,
<tt>nginx_clean</tt>, ...)

Returns:

  • (String) —

    user shell that is blocked



314
315
316
 
# File 'lib/nginx_stage/configuration.rb', line 314

def disabled_shell
  @disabled_shell
end

#mime_types_path ⇒ String

Path to system-installed NGINX mime.types config file

Returns:

  • (String) —

    the system-installed NGINX mime.types config



46
47
48
 
# File 'lib/nginx_stage/configuration.rb', line 46

def mime_types_path
  @mime_types_path
end

#min_uid ⇒ Integer

Minimum user id required to run the per-user NGINX as this user. This restricts running processes as special users (i.e., ‘root’)

Returns:

  • (Integer) —

    minimum user id required to run as user



307
308
309
 
# File 'lib/nginx_stage/configuration.rb', line 307

def min_uid
  @min_uid
end

#nginx_bin ⇒ String

Path to system-installed NGINX binary

Returns:

  • (String) —

    the system-installed NGINX binary



38
39
40
 
# File 'lib/nginx_stage/configuration.rb', line 38

def nginx_bin
  @nginx_bin
end

#nginx_signals ⇒ Array<Symbol>

A whitelist of signals that can be sent to the NGINX process

Returns:

  • (Array<Symbol>) —

    whitelist of NGINX process signals



42
43
44
 
# File 'lib/nginx_stage/configuration.rb', line 42

def nginx_signals
  @nginx_signals
end

#ondemand_portal ⇒ String?

Unique name of OnDemand portal for namespacing multiple portals

Returns:

  • (String, nil) —

    the name of OnDemand portal if defined



18
19
20
 
# File 'lib/nginx_stage/configuration.rb', line 18

def ondemand_portal
  @ondemand_portal
end

#ondemand_title ⇒ String?

Title of the OnDemand portal that apps should display in their navbar

Returns:

  • (String, nil) —

    the title of the Dashboard if defined



22
23
24
 
# File 'lib/nginx_stage/configuration.rb', line 22

def ondemand_title
  @ondemand_title
end

#ondemand_version_path ⇒ String

Path to the OnDemand version file that contains version of OnDemand installed

Returns:

  • (String) —

    the ondemand version file



14
15
16
 
# File 'lib/nginx_stage/configuration.rb', line 14

def ondemand_version_path
  @ondemand_version_path
end

#passenger_nodejs ⇒ String

Path to system-installed NodeJS binary

Returns:

  • (String) —

    the system-installed NodeJS binary



58
59
60
 
# File 'lib/nginx_stage/configuration.rb', line 58

def passenger_nodejs
  @passenger_nodejs
end

#passenger_python ⇒ String

Path to system-installed python binary

Returns:

  • (String) —

    the system-installed python binary



62
63
64
 
# File 'lib/nginx_stage/configuration.rb', line 62

def passenger_python
  @passenger_python
end

#passenger_root ⇒ String

Path to system-installed Passenger locations.ini file

Returns:

  • (String) —

    the system-installed Passenger locations.ini



50
51
52
 
# File 'lib/nginx_stage/configuration.rb', line 50

def passenger_root
  @passenger_root
end

#passenger_ruby ⇒ String

Path to system-installed Ruby binary

Returns:

  • (String) —

    the system-installed Ruby binary



54
55
56
 
# File 'lib/nginx_stage/configuration.rb', line 54

def passenger_ruby
  @passenger_ruby
end

#proxy_user ⇒ String

The reverse proxy daemon user used to access the sockets

Returns:

  • (String) —

    the reverse-proxy-daemon user



34
35
36
 
# File 'lib/nginx_stage/configuration.rb', line 34

def proxy_user
  @proxy_user
end

#pun_access_log_path(user:) ⇒ String

Path to the user’s personal access.log

Examples:

User Bob’s nginx access log

pun_access_log_path(user: 'bob')
#=> "/var/log/nginx/bob/access.log"

Parameters:

  • user (String) —

    the user of the nginx process

Returns:

  • (String) —

    the path to the nginx access log



99
100
101
 
# File 'lib/nginx_stage/configuration.rb', line 99

def pun_access_log_path(user:)
  File.expand_path @pun_access_log_path % {user: user}
end

#pun_app_configs(user:) ⇒ Array<Hash>

List of hashes that help define the location of the app configs for the per-user NGINX config. These will be arguments for #app_config_path.

Examples:

User Bob’s app configs

pun_app_configs(user: 'bob')
#=> [ {env: :dev, owner: 'bob', name: '*'},
      {env: :usr, owner: '*', name: '*'} ]

Parameters:

  • user (String) —

    the user of the nginx process

Returns:

  • (Array<Hash>) —

    list of hashes detailing app config locations



170
171
172
173
174
175
176
177
 
# File 'lib/nginx_stage/configuration.rb', line 170

def pun_app_configs(user:)
  @pun_app_configs.map do |envmt|
    envmt.each_with_object({}) do |(k, v), h|
      h[k] = v.respond_to?(:%) ? (v % {user: user}) : v
      h[k] = v.to_sym if k == :env
    end
  end
end

#pun_config_path(user:) ⇒ String

Root location where per-user NGINX configs are generated Path to generated per-user NGINX config file

Examples:

User Bob’s nginx config

pun_config_path(user: 'bob')
#=> "/var/log/nginx/config/puns/bob.conf"

Parameters:

  • user (String) —

    the user of the nginx process

Returns:

  • (String) —

    the path to the per-user nginx config file



75
76
77
 
# File 'lib/nginx_stage/configuration.rb', line 75

def pun_config_path(user:)
  File.expand_path @pun_config_path % {user: user}
end

#pun_error_log_path(user:) ⇒ String

Path to the user’s personal error.log

Examples:

User Bob’s nginx error log

pun_error_log_path(user: 'bob')
#=> "/var/log/nginx/bob/error.log"

Parameters:

  • user (String) —

    the user of the nginx process

Returns:

  • (String) —

    the path to the nginx error log



111
112
113
 
# File 'lib/nginx_stage/configuration.rb', line 111

def pun_error_log_path(user:)
  File.expand_path @pun_error_log_path % {user: user}
end

#pun_pid_path(user:) ⇒ String

Path to the user’s per-user NGINX pid file

Examples:

User Bob’s pid file

pun_pid_path(user: 'bob')
#=> "/var/run/nginx/bob/passenger.pid"

Parameters:

  • user (String) —

    the user of nginx process

Returns:

  • (String) —

    the path to the pid file



123
124
125
 
# File 'lib/nginx_stage/configuration.rb', line 123

def pun_pid_path(user:)
  File.expand_path @pun_pid_path % {user: user}
end

#pun_sendfile_root(user:) ⇒ String

Path to the local filesystem root where the per-user Nginx serves files from with the sendfile feature

Examples:

Filesystem root for user Bob

pun_sendfile_root(user: 'bob')
#=> "/"

Parameters:

  • user (String) —

    the user of the nginx process

Returns:

  • (String) —

    the path to the filesystem root that is served



148
149
150
 
# File 'lib/nginx_stage/configuration.rb', line 148

def pun_sendfile_root(user:)
  File.expand_path @pun_sendfile_root % {user: user}
end

#pun_sendfile_uri ⇒ String

The internal URI used to access the filesystem for downloading files from the browser, not including any base-uri

Examples:

pun_sendfile_uri
#=> "/sendfile"

Returns:

  • (String) —

    the internal URI used to access filesystem



160
161
162
 
# File 'lib/nginx_stage/configuration.rb', line 160

def pun_sendfile_uri
  @pun_sendfile_uri
end

#pun_socket_path(user:) ⇒ String

Path to the user’s per-user NGINX socket file

Examples:

User Bob’s socket file

socket_path(user: 'bob')
#=> "/var/run/nginx/bob/passenger.sock"

Parameters:

  • user (String) —

    the user of nginx process

Returns:

  • (String) —

    the path to the socket file



135
136
137
 
# File 'lib/nginx_stage/configuration.rb', line 135

def pun_socket_path(user:)
  File.expand_path @pun_socket_path % {user: user}
end

#pun_tmp_root(user:) ⇒ String

Path to user’s personal tmp root

Examples:

User Bob’s nginx tmp root

pun_tmp_root(user: 'bob')
#=> "/var/lib/nginx/tmp/bob"

Parameters:

  • user (String) —

    the user of the nginx process

Returns:

  • (String) —

    the path to the tmp root



87
88
89
 
# File 'lib/nginx_stage/configuration.rb', line 87

def pun_tmp_root(user:)
  File.expand_path @pun_tmp_root % {user: user}
end

#template_root ⇒ String

Location of ERB templates used as NGINX configs

Returns:

  • (String) —

    the ERB templates root path



26
27
28
 
# File 'lib/nginx_stage/configuration.rb', line 26

def template_root
  @template_root
end

#user_regex ⇒ Regexp

Regular expression used to validate a given user name

Returns:

  • (Regexp) —

    user name regular expression



298
299
300
 
# File 'lib/nginx_stage/configuration.rb', line 298

def user_regex
  /\A#{@user_regex}\z/
end

Class Method Details

.extended(base) ⇒ Object

Sets default configuration options in any class that extends NginxStage::Configuration



339
340
341
 
# File 'lib/nginx_stage/configuration.rb', line 339

def self.extended(base)
  base.set_default_configuration
end

Instance Method Details

#configure {|config| ... } ⇒ void

This method returns an undefined value.

Yields the configuration object.

Yield Parameters:



334
335
336
 
# File 'lib/nginx_stage/configuration.rb', line 334

def configure
  yield self
end

#default_config_path ⇒ String

Default configuration file

Returns:

  • (String) —

    path to default yaml configuration file



322
323
324
325
326
327
328
329
 
# File 'lib/nginx_stage/configuration.rb', line 322

def default_config_path
  config = config_file
  unless File.file?(config)
    config = File.join root, 'config', 'nginx_stage.yml'
    warn "[DEPRECATION] The file '#{config}' is being deprecated. Please move this file to '#{config_file}'." if File.file?(config)
  end
  config
end

#read_configuration(file) ⇒ void

This method returns an undefined value.

Read in a configuration from a file

Parameters:

  • file (String) —

    path to the yaml configuration file



415
416
417
418
419
420
421
422
423
424
 
# File 'lib/nginx_stage/configuration.rb', line 415

def read_configuration(file)
  config_hash = symbolize(YAML.load_file(file)) || {}
  config_hash.each do |k,v|
    if instance_variable_defined? "@#{k}"
      self.send("#{k}=", v)
    else
      $stderr.puts %{Warning: invalid configuration option "#{k}"}
    end
  end
end

#set_default_configuration ⇒ void

This method returns an undefined value.

Sets the default configuration options



345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
 
# File 'lib/nginx_stage/configuration.rb', line 345

def set_default_configuration
  self.ondemand_version_path = "/opt/ood/VERSION"
  self.ondemand_portal       = nil
  self.ondemand_title        = nil
  self.template_root         = "#{root}/templates"

  self.proxy_user       = 'apache'
  self.nginx_bin        = '/opt/rh/nginx16/root/usr/sbin/nginx'
  self.nginx_signals    = i(stop quit reopen reload)
  self.mime_types_path  = '/opt/rh/nginx16/root/etc/nginx/mime.types'
  self.passenger_root   = '/opt/rh/rh-passenger40/root/usr/share/passenger/phusion_passenger/locations.ini'
  self.passenger_ruby   = "#{root}/bin/ruby"
  self.passenger_nodejs = "#{root}/bin/node"
  self.passenger_python = "#{root}/bin/python"

  self.pun_config_path     = '/var/lib/nginx/config/puns/%{user}.conf'
  self.pun_tmp_root        = '/var/lib/nginx/tmp/%{user}'
  self.pun_access_log_path = '/var/log/nginx/%{user}/access.log'
  self.pun_error_log_path  = '/var/log/nginx/%{user}/error.log'
  self.pun_pid_path        = '/var/run/nginx/%{user}/passenger.pid'
  self.pun_socket_path     = '/var/run/nginx/%{user}/passenger.sock'
  self.pun_sendfile_root   = '/'
  self.pun_sendfile_uri    = '/sendfile'
  self.pun_app_configs     = [
    {env: :dev, owner: '%{user}', name: '*'},
    {env: :usr, owner: '*',       name: '*'},
    {env: :sys, owner: '',        name: '*'}
  ]

  self.app_config_path   = {
    dev: '/var/lib/nginx/config/apps/dev/%{owner}/%{name}.conf',
    usr: '/var/lib/nginx/config/apps/usr/%{owner}/%{name}.conf',
    sys: '/var/lib/nginx/config/apps/sys/%{name}.conf'
  }
  self.app_root          = {
    dev: '~%{owner}/%{portal}/dev/%{name}',
    usr: '/var/www/ood/apps/usr/%{owner}/gateway/%{name}',
    sys: '/var/www/ood/apps/sys/%{name}'
  }
  self.app_request_uri   = {
    dev: '/dev/%{name}',
    usr: '/usr/%{owner}/%{name}',
    sys: '/sys/%{name}'
  }
  self.app_request_regex = {
    dev: '^/dev/(?<name>[-\w.]+)',
    usr: '^/usr/(?<owner>[\w]+)/(?<name>[-\w.]+)',
    sys: '^/sys/(?<name>[-\w.]+)'
  }
  self.app_token = {
    dev: 'dev/%{owner}/%{name}',
    usr: 'usr/%{owner}/%{name}',
    sys: 'sys/%{name}'
  }
  self.app_passenger_env = {
    dev: 'development',
    usr: 'production',
    sys: 'production'
  }

  self.user_regex     = '[\w@\.\-]+'
  self.min_uid        = 1000
  self.disabled_shell = '/access/denied'

  read_configuration(default_config_path) if File.file?(default_config_path)
end