StuartEllis.eu

An Introduction to ERB Templating

2011-02-06T17:53:00Z

Overview

ERB is a feature of Ruby that enables you to conveniently generate any kind of text, in any quantity, from templates. The templates themselves combine plain text with Ruby code for variable substitution and flow control, which makes them easy to write and maintain.

Although ERB is most commonly seen generating Web pages, it is also used to produce XML documents, RSS feeds, source code, and other forms of structured text file. It can be extremely valuable when you need to create files which include many repetitions of a standard pattern, such as unit test suites.

The main component of ERB is a library which you can call within your Ruby applications and Rake tasks. This library accepts any string as a template, and imposes no limitations on the source of the template. You may define a template entirely within your code, or store it in an external location and load it as required. This means that you can keep templates in files, SQL databases, or any other kind of storage that you want to use.

Ruby distributions also include a command-line utility that enables you to process templates that are held in files without writing any additional code. Logically, this utility is called erb.

ERB is part of the Ruby standard library. You do not need to install any other software to use it.

The supplied documentation for ERB provides a good introduction:

ri ERB

Writing Templates

ERB copies the text portions of the template directly to the generated document, and only processes code that is identified by markers. Most ERB templates only use a combination of two tag markers, each of which cause the enclosed code to be handled in a particular way.

A tag with an equals sign indicates that enclosed code is an expression, and that the renderer should substitute the code element with the result of the code (as a string) when it renders the template. Use an expression to embed a line of code into the template, or to display the contents of a variable:


1
2

  Hello, <%= @name %>.
Today is <%= Time.now.strftime('%A') %>.

Tags without the equals sign denote that the enclosed code is a scriptlet. Each scriptlet is caught and executed, and the final result of the code is then injected in to the output at the point of the scriptlet.

Scriptlets are most commonly used for embedding loops or conditional logic into templates:


1
2
3
4
5

  <ul>
  <% for @item in @shopping_list %>
    <li><%= @item %></li>
  <% end %>
</ul>

Notice that the scriptlets in this example enclose an expression. The scriptlets produce no text themselves, but cause the enclosed expression to run multiple times, and the result of the expression is written to the output each time.

Comment markers use a hash sign:




  <%# This is just a comment %>

By default, a newline character is added to the page after the position of each tag. To suppress this newline, use the optional parameter of ERB.new(), as explained below.

Rails extends ERB, so that you can suppress the newline simply by adding a trailing hyphen to tags in Rails templates:


1
2
3
4
5

  <ul>
  <% for @item in @items -%>
    <li><%= @item %></li>
  <% end -%>
</ul>

Using Text Transformation Methods

ERB provides optional methods for transforming text:


1
2
3
4

  This will be HTML escaped: <%= h(this & that) %>
This will be JSON encoded: <%= j(this & that) %>
This will be converted to Textile markup: <%= t(this & that) %>
This will be URL encoded: <%= u(this & that) %>

To use these features your code must include the module ERB::Util.

Conventions for Template Files

A file that contains an ERB template may have any name, but it is the convention that the name of file should end with the .erb extension. Rails requires template files to have the extension of the output type, followed by .erb, so that a name like layout.html.erb indicates a HTML template. Some applications use the extension .rhtml for HTML templates.

If you store templates in files, it is good practice to keep each template in a separate file.

Using the ERB Library

This is a very simple example:


1
2
3
4
5
6
7

  require 'erb'

weekday = Time.now.strftime('%A')
simple_template = "Today is <%= weekday %>."

renderer = ERB.new(simple_template)
puts output = renderer.result()

ERB only processes the template when result is called. This means that the output will show the values of variables as they are at the moment when the result is rendered, not when the ERB object was defined.

The code shown above will fail almost anywhere other than in a simple script. ERB gets variables from a Binding, an object that provides access to the instance methods and variables that are owned by another object. If you do not specify a Binding, the result() method gets a Binding from the top-level object, which will probably own very little. Fortunately, every Ruby class has a private binding() instance method to provide Bindings that points to itself, so we can easily extend any object to provide ERB with a Binding.

If the ERB object is enclosed in a method, and we want it to use the variables of the host object, we get a Binding for the host like this:


1
2
3
4
5
6
7

  class ShoppingList
  attr_accessor :items, :template

  def render()
    renderer.result(binding)
  end
end

To enable ERB to use the variables from a separate object, we must first ensure that it has a public method to provide a Binding. We can then get a Binding at any later point:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

  class ShoppingList
  attr_accessor :items

  def initialize(items)
    @items = items
  end

  # Expose private binding() method.
  def get_binding
    binding()
  end

end

list = ShoppingList.new(items)
renderer = ERB.new(template)
puts output = renderer.result(list.get_binding)

Running ERB in a Sandbox

You may protect your application from ERB by running it in a new thread. If you specify an integer as a second parameter when you create the renderer, then the template will be processed in a new thread which has a safe level equal to the given integer:


1

  renderer = ERB.new(template, 3)

Safe level 4 provides maximum isolation. At this level, the specified binding must be marked as trusted for ERB to use it.

If you need to set the third or fourth parameters, but do not want ERB to run in a new thread, use 0 as the second parameter.

Suppressing Newlines

The third parameter of new specifies optional modifiers, most of which alter when newline characters will be automatically added to the output. For example, ERB will not print newlines after tags if you give > as the third parameter:


1

  renderer = ERB.new(template, 3, '>')

A Longer Example


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

  require 'erb'

def get_items()
  ['bread', 'milk', 'eggs', 'spam']
end

def get_template()
  %{
        <DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    <head>
            <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
            <title>Shopping List for <%= @date.strftime('%A, %d %B %Y') %></title>
        </head>
        <body>
                 <h1>Shopping List for <%= @date.strftime('%A, %d %B %Y') %></h1>
                <p>You need to buy:</p>
                <ul>
                  <% for @item in @items %>
                    <li><%= h(@item) %></li>
                  <% end %>
                </ul>
        </body>
        </html>
  }
end

class ShoppingList
  include ERB::Util
  attr_accessor :items, :template, :date

  def initialize(items, template, date=Time.now)
    @date = date
    @items = items
    @template = template
  end

  def render()
    ERB.new(@template).result(binding)
  end

  def save(file)
    File.open(file, "w+") do |f|
      f.write(render)
    end
  end

end

list = ShoppingList.new(get_items, get_template)
list.save(File.join(ENV['HOME'], 'list.html'))

Running ERB from the Command-line

The erb utility processes a given template and sends the result to the standard output. This enables you to generate files directly from templates, by redirecting the output:

erb my-template.txt.erb > new-file.txt

The template can automatically use built-in Ruby classes, such as String and File. To allow it to access standard or third-party libraries, use the -r option. This option works in the same way as the require keyword. This example processes a template that uses the Abbrev and IPAddr libraries:

erb -r abbrev -r ipaddr my-template.txt.erb  > new-file.txt

Use the -S option to specify a safe level that isolates the template processing:

erb -S 4 my-template.txt.erb > new-file.txt

Safe levels are explained above.

Other Resources

The ERB documentation

These books explain ERB (and many other things):

Using Rake to Automate Tasks

2011-02-06T17:52:00Z

Rake enables you to define a set of tasks and the dependencies between them in a file, and then have the right thing happen when you run any given task. Each task may be either one of the built-in types, or a block of your own Ruby code. It was originally created to handle software build processes, but the combination of convenience and flexibility that it provides has made it the standard method of job automation for Ruby projects.

You may use supplied methods in your task code to conveniently set up common jobs, such as running test suites, publishing files and packaging software. Equally, you may call or write any other Ruby code into a Rake task, which means that it can automate just about anything.

Crucially, you also write the task and dependency definitions themselves in Ruby, following a specific format. This means that you do not need to deal with any new syntax to start automating your routine jobs. Anyone with a basic knowledge of Ruby can understand and maintain Rake tasks.

Rake is Declarative

Rake itself is designed to be a declarative system – you specify the result that you want, and Rake carries out the associated task and dependent tasks as necessary. This means that a set of correctly defined tasks will do as little or as much as is necessary to produce a known state.

The task types that are supplied with Rake follow this approach. For example, the built-in types of tasks for creating file and directories creation automatically check for the specified item, and will not run if an up to date copy exists.

Project and Global Rake Task Files

By default, the Rake utility checks the current working directory for a file with the name Rakefile (with no extension). This enables you to add a file of Rake tasks to the source code of any application without conflicting with the names of existing files. If you would like to create one or more specifically named Rake files in a directory, use the file extension .rake for them.

To make a set of Rake tasks available for use from any directory, create a .rake subdirectory within your home directory, and place the appropriate Rake files there. Any rake command with the -g option will use these global Rake files:

rake -g -T

Installing Rake

Rake is now part of the Ruby standard library, and will automatically be part of any Ruby 1.9 installation. Alternative Ruby implementations such as JRuby usually also include Rake.

To install Rake for Ruby 1.8, use RubyGems:

gem install rake

Using Existing Rake Tasks

Many Ruby projects and applications provide a set of Rake tasks, so you may well start using Rake before you have written a task file yourself. For example, every Ruby on Rails project automatically includes a large number of tasks which can be run from the root directory of the project.

Getting a List of the Available Tasks

To see a list of all of the tasks available from the current Rake file, use the -T option of the rake utility:

rake -T

Running a Task

To run a named task, specify the name of the task:

rake my_task

Notice that the task name has no colon prefix here.

To run a Rake file or directory task, use the name of the file or directory:

rake mydoc.pdf

If you call rake without specifying any task, it automatically checks for a task named default, and runs that task if one is found.

rake

Specifying Options

All of the options of the rake utility may be called with either a single letter switch, or a longer word version. Note that command-line options may go before or after the name of the task, whichever you prefer:

rake my_task --quiet
rake --quiet my_task

The --quiet option suppresses any output that individual tasks would usually display in your terminal window, but allows errors to be shown normally.

A later section explains some of the most used options. To see a list of all of the available options, run rake with -h, or --help:

rake -h
rake --help

Writing Rake Files

A Rake file does not need to have anything in it, other than task definitions. In addition to the tasks, you may freely use standard Ruby elements, including constants and methods.

Remember to set a default task: It’s a good habit to specify a default task in each Rake file (as explained below).

Task Definitions

Each task definition consists of:

A description
The name that identifies the task
The code to be executed by the task

In addition, you can specify input parameters for your tasks, and other tasks that are prerequisites.

For standard tasks, the name of the task is a Ruby symbol, which means that it must be prefixed by a colon, and also must use only lowercase alphanumeric characters, with underscores instead of spaces. We only use the colon prefix for specifying task names within Rake files, not when we actually run the tasks.

Multiple Tasks with the Same Name: If you define two tasks with same name, Rake appends the second task of that name to the first.

The actual code for the task to run must be enclosed in a standard Ruby do…end block. This is the structure of a simple task:


1
2
3
4

  desc "One line task description"
task :name_of_task do
  # Your code goes here
end

The task shown above accepts no input parameters, and has no prerequisites, so we completely omitted these items to make the definition more compact. If we did not include a description, the task would still work, but it would not appear on listings.

This task depends on two other tasks:


1
2
3
4

  desc "Example of a task with prerequisites"
task :third_task => ["first_task", "second_task"] do
  # Your code goes here
end

When we run the task shown above, Rake first checks the prerequisites. It then executes all of the prerequisite tasks before it actually carries out the requested task.

To run a task, we simply call the rake utility at a command prompt, and specify the task:

rake name_of_task

The Initial Working Directory: To ensure that paths are consistent, all tasks run with an initial working directory that matches the directory of the Rake file that holds them. Do not assume that the working directory of a task is the current working directory of the user that runs the task.

Input Parameters for Tasks

Rake refers to the input parameters for tasks as arguments. This task has both arguments and prerequisites:


1
2
3
4
5
6

  desc "Example of task with parameters and prerequisites"
task :my_task, [:first_arg, :second_arg] => ["first_task", "second_task"] do |t, args|
  args.with_defaults(:first_arg => "Foo", :last_arg => "Bar")
  puts "First argument was: #{args.first_arg}"
  puts "Second argument was: #{args.second_arg}"
end

The first line of the task assigns default values to the arguments.

To run a task that requires arguments, we must specify the values for each of the arguments after the name of the task:

rake my_task[one,two]

Notice that there are no spaces where the task is specified, either between the name of the task and the opening square bracket, or between the first and second argument.

If you do not give a value for an argument at the command-line, and the task does not specify a default value, the value of the argument is set to nil.

Setting a Default Task

For convenience, define a dummy task called default that depends on one or more of your tasks, and has no code itself. If a user runs the rake utility without specifying a task, it automatically runs the default task in the Rakefile.


1

  task :default => ["my_task"]

This command now carries out the default task:

rake

Running One Task with Another

Normally, you link tasks together with dependencies. If you need to run a task from within another, use the invoke method:


1
2
3
4

  desc "Example of task with invoke"
task :first_task do
  Rake::Task[:second_task].invoke
end

This code returns the specified task as a Rake::Task, and calls the invoke method of the task object.

Managing Files and Directories with Rake

File and Directory Generation Tasks

File and directory creation tasks are identified by the item that they generate, rather than by an arbitrary name. Any file or directory task may use either full or partial names. Note that you must use glob patterns to define any partial names, not regular expressions. This provides consistency with the standard Ruby file and directory functions, which also use glob patterns.


1
2
3

  file 'mydoc.pdf' => ['mydoc.xml', 'mydoc.xslt'] do
  # Code goes here...
end

If a task specifies a target file, then Rake checks both that the file exists, and also that it is not older than the files specified by any prerequisite tasks. Rake only runs the task associated with the file if the target is either not present, or if it is not up to date. As a result, Rake tasks can efficiently maintain even a very large set of files.

Directory tasks just create the specified directories, if they do not already exist. These consist of the keyword directory, followed by the directory itself. Directory tasks may not have either a code block, nor any prerequisites. Other tasks may use a directory task as a prerequisite:


1
2
3
4
5

  directory 'html'

  file 'html/contents.html' => ['html', 'html/index.html'] do
    # Code goes here...
  end

As you would expect, standard tasks may have file or directory tasks as prerequisites:


1
2
3

  task :upload_page => 'myfile.html' do
  # Your code...
end

Rather than tying tasks to specific file or directory names, you may use FileLists or Rules, as explained below.

Defining Sets of Files with FileLists

A FileList is an array of complete and partial file names, written in the Rake file itself (or one of the imported modules).


1

  my_files = FileList['build/*.html', 'index.xml']

Excluded Files: By default, FileLists never returns certain types of file, even if a glob would match them. Suppressed file types include administrative files and directories for version control systems, UNIX backup files, and core dumps.

Using the Clean-up Tasks

Rake includes two tasks to clean up a set of files, so that you do not need to write code to handle this kind of job. Simply require the rake/clean module, and add values to the FileLists called CLEAN and CLOBBER, which are part of the module. Any file that is in the CLEAN FileList will be deleted when you run the clean task. Similarly, clobber deletes anything included in the CLOBBER list.


1
2
3

  require 'rake/clean'
CLEAN.include('*.tmp')
CLOBBER.include('*.tmp', 'build/*')

Having two tasks with separate FileLists enables you to target either just those files that were created by running build tasks, or purge any file that should not be mixed in with the set. Set up the CLEAN list to specifically handle temporary build files, and CLOBBER to aggressively match all potentially unwanted files.

Other File Handling Methods

Rake automatically provides file handling methods, to enable you to write tasks that include the usual operations. For convenience, these methods have similar names to the equivalent UNIX utilities, such as cp and mv.

Here are two contrived examples:


1
2
3
4
5
6
7

  task :copy_files do
  cp('readme.htm', File.join('build', 'readme.htm'), :verbose => true)
end

task :mv_files do
  mv(File.join('build', 'readme.htm'), File.join('release', 'index.htm'), :verbose => true)
end

These methods are provided by RakeFileUtils, an extended version of the standard Ruby module FileUtils. To see all of the available methods, refer to the FileUtils documentation:

ri FileUtils

Use the standard tasks where possible, rather than these utility methods.

Rules

A rule defines filenames, and a block of Ruby code. For each matching file, the rule creates and runs a new task with the specified code. You may use either names or regular expressions to define the files that match the rule.

Using Other Ruby Libraries in Rake Tasks

Your Rake files may reference other Rake files or Ruby modules. Use require statements as normal to import modules, or other Rake files.

Rake includes built-in methods for many common tasks, so before you write or import other code, check the documentation to see if a suitable method already exists within Rake.

This example uses the ERB template system, which is part of the Ruby standard library:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

  require 'erb'

OUTPUT_FILE='README.html'
TEMPLATE_FILE='template.html.erb'

def get_template
  File.read(TEMPLATE_FILE)
end

desc "Builds the HTML file, using ERB."
file OUTPUT_FILE do
  File.open(OUTPUT_FILE, "w+") do |f|
    f.write(ERB.new(get_template).result())
  end
end

task :default => [OUTPUT_FILE]

The code shown above uses a standard Ruby method from the File class to get the template from a file as a string, creates an ERB renderer to process the template string, and writes the output to the target file.

Integrating with the Shell

Rake and Ruby work consistently across platforms, making them a portable alternative to shell scripts, but you may also use them as a means of automating platform-specific features. This section briefly describes how you can use the shell integration facility of Rake to call command-line utilities from within your own tasks.

Using Shell Commands in Rake Tasks

To handle shell commands in your Rake tasks, use the sh method. This is provided by an extension to the FileUtils module, so you need to require that module in the task file before you can call the method:


1
2
3
4
5
6
7

  require 'fileutils'

# Stuff...

task :run_command do
  sh %{ space separated command and options }
end

The sh method passes two outputs: a status, and the actual output of the command. This example from the Rake documentation makes it clear:


1
2
3
4
5

  sh %{grep pattern file} do |ok, res|
  if ! ok
    puts "pattern not found (status = #{res.exitstatus})"
  end
end

As always, remember that using shell commands restrict your software to systems that have those exact utilities installed. Use Ruby code unless you require the features of a particular command-line utility, such as a configuration tool that is specific to one operating system.

Using Environment Variables

Rake automatically recognises the environment variables provided by the shell. You may also create or set environment variables specifically for tasks at the same time as you run Rake.

This code uses two environment variables, the standard HOME variable, and a MY_VAR that was set at run-time:


1
2
3
4
5
6

  desc "Task description"
task :name_of_task do
  my_setting1 = ENV['HOME']
  my_setting2 = ENV['MY_VAR']
  # Your code goes here
end

See below for information on how to set variables at run-time.

Outputting Messages to the Shell

By default, Rake echoes error messages and the file handling operations of RakeFileUtils to the shell. You can use standard Ruby methods to output your own messages as normal:


1
2
3
4

  desc "Task description"
task :name_of_task do
  puts "foo bar"
end

Your output appears even if Rake runs with the --quiet or --silent options.

Managing Large Numbers of Tasks

If the number of required tasks in a set begins to grow, you can ensure that they remain easy to use and maintain with two techniques. First, you can assign some of your tasks to separate namespaces, so that task names remain unique and unambiguous. Second, you can write code into the Rake file to dynamically generate tasks, enabling it to create many variations of the same process, or adapt the available tasks to the host system.

Using Namespaces to Organize Tasks

To avoid duplicate or ambiguous names in large sets of tasks, enclose some of the tasks in namespaces. By convention, each namespace should be identified by one word, in lowercase. You may nest your namespaces, as this example shows:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

  namespace 'build' do

  # tasks...  

end

namespace 'test' do

   # tasks...

  namespace 'unit' do
   # tasks...
  end

end

To reference a task that is within a namespace, prefix the name of the task with the namespace and a colon:


1
2
3
4

  desc "Example of a task with namespaced prerequisites"
task :third_task => ["build:first_task", "test:unit:second_task"] do
  # Your code goes here
end

The command-line utility uses the same naming convention:

localhost:railsapp me$ rake -T
(in /Users/me/railsapp)
...
rake rails:freeze:edge                    # Lock to latest Edge Rails
rake rails:freeze:gems                    # Lock this application to the current gems
rake rails:template                       # Applies the template supplied by LOCATION
rake rails:unfreeze                       # Unlock this application from freeze of gem
...

The above was taken from the task list of a standard Ruby on Rails application.

Defining Tasks Dynamically

To dynamically generate task definitions as the task file runs, directly integrate the definition keywords into Ruby code. All of the Rake keywords are actually Ruby methods that declare tasks, descriptions and namespaces as the tasks file is executed.

The example shown below dynamically creates a suite of tasks by loading YAML format configuration files from a directory. It produces a separate namespace for each configuration file.


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

  require 'yaml'

# Uses FileList to get an Array of the configuration files
CONFIG_FILES=FileList['config/*.yml']

# Returns the configuration from the file as a Hash object
def get_config(file)
  YAML.load_file(file)
end

CONFIG_FILES.each do |f|

  config = get_config(f)
  
  namespace config[:name] do

    # Generate tasks

    desc "First task for #{config[:name]}"
    task config[:first] do
      # Code goes here
    end

    desc "Second task for #{config[:name]}"
    task config[:second] do
      # Code goes here
    end

    # more...

  end

end

This approach enables us to cleanly generate multiple tasks with appropriate namespaces. If we only needed to generate a task for each file, we could make an even simpler routine by using a Rule to create the tasks.

More Advanced Options for Running Rake Tasks

The rake utility provides many options. Some of these options are useful in many situations for testing, or for working around issues with the host system.

Specifying the Location of the Tasks File

To use a specific Rake file of your choice, use either -f, or --rakefile:

rake --rakefile my_task_file my_task

To use tasks from the Rake files from your .rake directory, use the -g option:

rake -g -T
rake -g my_task

This option automatically uses all of the .rake files in the directory.

Suppressing the Output of Tasks

The --quiet option only suppresses normal output. Use --silent to run Rake with absolutely no output at all:

rake --silent my_task

Specifying Environment Variables for a Task

To specify environment variables for your tasks along with your command, simply use the format variable=value:

rake my_task my_var1='Some value' my_var2='Another value'

Debugging Tasks

Finally, to debug a Rake task, either use the --dry-run option to see what steps it will take, without actually executing them, or specify --trace to see detailed output:

rake --dry-run my_task
rake --trace my_task

Remember that Ruby itself includes a debugger that works on the command-line.

Other Automation Tools

Beyond Rake, Ruby has a broad range of other useful automation software. These are a few of the most well-known:

The Thor scripting framework provides a powerful general-purpose system for defining and running tasks.
Capistrano is the leading utility for automating server application deployments and upgrades.
Vlad is a rival to Capistrano which directly extends Rake.
Puppet enables you to automate the management of a network of varied systems, throughout their lifecycle.
Chef provides an alternative to Puppet that is perhaps more suited to Ruby developers who must maintain application servers.

Useful Resources

Tutorials

Reference Documents

Hints and Tips

Linux and UNIX Security Features

2011-02-06T17:50:00Z

An introduction to the security facilities of Open Source UNIX-like operating systems, focusing on Linux distributions.

User Accounts

Every UNIX-like system includes a root account, which is the only account that may directly carry out administrative functions. All of the other accounts on the system are unprivileged. This means these accounts have no rights beyond access to files marked with appropriate permissions, and the ability to launch network services.

Network Ports: Only the root account may launch network services that use port numbers lower than 1024. Any account may start network services that use higher port numbers.

Each user should have a single account on the system. Network services may also have their own separate accounts, in order to be able to access those files on the system that they require. Utilities enable authorized users to temporarily obtain root privileges when necessary, so that administrators may manage the system with their own user accounts.

Avoid Logging in as root: You do not need to log in with the root account in order to manage any aspect of your system. Use tools such as su or sudo when you need to carry out an administrative task that requires root privileges.

For convenience, accounts may be members of one or more groups. If a group is assigned access to a resource, then every member of the group automatically has that access.

User Private Groups: On many distributions, each account is automatically made the sole member of a group with the same name as the account. This enables you to easily limit access to particular files or directories, by associating them with a group that will only ever have one member.

The majority of UNIX-like systems use a Pluggable Authentication Modules (PAM) facility to manage access by users. For each login attempt or password change, the relevant service runs the configured PAM modules in sequence. Some modules support authentication sources, such as locally-stored files or LDAP directory services. Administrators may enable other modules that carry out setup tasks during the login process, or check login requests against particular criteria, such as a list of time periods when access is permitted.

File Permissions

Every file and directory on a UNIX-style system is marked with three sets of file permissions that determine how it may be accessed, and by whom:

The permissions for the owner, the specific account that is responsible for the file
The permissions for the group that may use the file
The permissions that apply to all other accounts

Each set may have none or more of the following permissions on the item:

read
write
execute

A user may only run a program file if they belong to a set that has the execute permission. For directories, the execute permission indicates that users in the relevant set may see the files within it, although they may not actually read, write or execute any file unless the permissions of that file permit it. Executable files with the setUID property automatically run with the privileges of the file owner, rather than the account that activates them. Avoid setting the execute permission or setUID on any file or directory unless you specifically require it.

root Ignores File Permissions: The root account has full access to every file on the system, regardless of the permissions attached to that file.

The majority of files on a UNIX-like system are owned by the root account, and have permissions that restrict or block access from all other accounts. Avoid modifying the permissions on system files and directories.

Historically, user home directories on UNIX-like systems were publicly readable, to facilitate sharing between academic colleagues. Unfortunately, some popular operating systems still make user home directories publicly readable by default.

Access Control Lists: Many, but not all, modern UNIX-like systems include support for a more flexible set of permissions known as Access Control Lists (ACLs). Unfortunately, some common applications are not fully compatible with ACL permissions.

Data Verification

To create a checksum for a file, or to test a file against a checksum, use the sha1sum utility. SHA1 supersedes the older MD5 method, and you should always use SHA1. For more information about about sha1sum, refer to the manual:

man sha1sum

Open Source UNIX-like systems also supply the GNU Privacy Guard (GnuPG) system for encrypting and digitally signing files, such as emails. Many documents refer to GnuPG as gpg, which is the name of the main GnuPG command.

GnuPG Follows the OpenPGP Standard: The files that you sign or encrypt with GnuPG are compatible with other applications that follow the OpenPGP standard.

The Evolution email application automatically supports both signing and encrypting emails with GnuPG. Evolution is the default email application for several of the main Linux distributions, including Fedora, Novell Linux Desktop, Red Hat Enterprise Linux, and Ubuntu.

To use other GnuPG features in the GNOME desktop environment, install Seahorse through the standard software management tool for your distribution. For more information on Seahorse, refer to the project Web site:

http://www.gnome.org/projects/seahorse/

To integrate GnuPG with Mozilla Thunderbird, add the Enigmail extension to Thunderbird. Refer to the Enigmail Web page for installation instructions and other details:

http://enigmail.mozdev.org/

For more information on GnuPG itself, refer to the project Web site:

http://www.gnupg.org/

Encrypted Storage

Create one or more encrypted volumes for your sensitive files. Each volume is a single file which may enclose other files and directories of your choice. To access the contents of the volume, you must provides the correct decryption password to a utility, which then makes the volume available as if it were a directory or drive. The contents of an encrypted volume cannot be read when the volume is not mounted. You may store or copy encrypted volume files as you wish without affecting their security.

The cross-platform Truecrypt utility enables you to create and access your encrypted volumes with all popular operating systems:

http://www.truecrypt.org/

In extreme cases, you may decide to encrypt an entire disk partition that holds or caches data, so that none of the contents may be read by unauthorized persons. On Linux you may use either LUKS, CryptoFS, or EncFS to encrypt disks. Unfortunately, many UNIX-like systems do not yet integrate support for disk encryption facilities into their installation and management software, which makes configuration and maintenance more difficult. Disk encryption also reduces performance, and this may not be acceptable for systems that run demanding applications.

Secure Remote Access with OpenSSH

Every common UNIX-like system today includes a version of OpenSSH, an implementation of the SSH standard for secure remote access. An SSH service uses strong encryption by default, and provides the following facilities:

Remote command-line access
Remote command execution
Remote access to graphical software
File transfers

In addition, the forwarding features of SSH allow you to tunnel connections to other services through SSH. A tunneled service benefits from the same security and data compression features as the built-in facilities of SSH. This enables you to protect almost all communications between any UNIX-like systems, even when the traffic passes over open wireless networks or the public Internet.

SSH software not only encrypts the connection between systems, but also uses a system of keys to provide mutual authentication between each party. Each SSH client utility automatically checks the identity of any remote system that it connects to, by verifying the key. Similarly, users may identify themselves to systems with a key, rather than typing potentially crackable passwords.

Use SSH by Default: SSH potentially offers the most secure method of remote access available today. The standard Open Source desktop environments now also support SSH as a standard method for working with remote files. Only enable access to your systems through other services if you need to do so in order to meet a specific requirement.

Most Linux distributions include the OpenSSH client by default. The OpenSSH service as usually offered as an option, although some distributions also provide it by default. Mac OS X includes both the OpenSSH service, and the client utilities. To access SSH services from Microsoft Windows systems, install PuTTY. You may download PuTTY from the main project Web site:

http://www.chiark.greenend.org.uk/%7Esgtatham/putty/

FileZilla, WinSCP, and other file transfer utilities for Microsoft Windows also support SSH.

The OpenBSD project maintains the OpenSSH software and Web site:

http://www.openssh.com/

Software Management

The majority of Linux distributions incorporate software management facilities based on package files and sets of specially prepared Web sites, known as repositories or channels. Package management utilities construct or update working copies of software from these packages, and execute any other setup tasks that packages require. Repositories enable the management tools to automatically provide the correct version of each software product, by downloading the required packages directly from the relevant repository. Most systems also use checksums and digital signature tests to ensure that packages are authentic and correct.

In addition, package management tools can identify outdated versions of software by checking the software installed on a system against the packages in the repositories. This means that you can ensure that all of the supported software on your system does not suffer from a known security vulnerability, simply by running the update routine.

Most desktop systems now automatically alert you when new versions of the installed packages are released to the repositories, and provide options to update your system. Graphical interfaces to their software management tools also enable you to browse and select new software from the available packages.

Use packages from repositories whenever possible, in order to guarantee the provenance of the software on your system, and to ensure that it remains current. If you use software from elsewhere then you will need to verify, install, and update those products yourself. In these cases, download the software directly from the Web site of the manufacturer. Package management tools cannot inventory, check, or maintain any software that was compiled from source code, so you must be particularly careful when you use manually compiled products.

For historical reasons, the main Linux distributions use different package management products. Fedora, Red Hat Enterprise Linux, and related distributions, use the RPM package format, and their software management facility is known as YUM. Debian, Ubuntu, and their derivatives, use the APT management system and the DEB package format. These systems and package formats are largely equivalent.

Host Integrity Testing

To verify that a running system has not been compromised or tampered with, use an integrity testing facility. All host integrity testing software verifies a complete copy of a system by testing each file against a previously made checksum. Solaris and FreeBSD distributions both now include integrity testing utilities for this purpose. You may also use a cross-platform integrity monitoring system, such as Samhain or Osiris. Both Osiris and Samhain support centralized system auditing for multiple systems.

Since system configurations vary, administrators must configure the integrity tester to exclude the particular directories and files that are expected to change on a system, before creating an initial checksum database for that system. Integrity testing can then compare the checksums of each file against the database, and report on any disparity.

System Recovery

You may easily restore program files for all of the software that is included with your distribution with the software management tools. In order to fully recover a system from accident, or deliberate compromise, you must also have access to copies of the data, configuration, and log files. These files require some form of separate backup mechanism.

All effective backup systems provide the ability to restore versions of your files from several earlier points in time. You may discover that the current system is damaged or compromised at any time, and need to revert to previous versions of key files, so keeping only one additional copy of a key file should not be considered an adequate backup.

Duplicates Are Not Archives: File synchronization software and RAID storage make duplicate copies of the current files, and may act as a safeguard against data loss from hardware failures. Unlike backup systems, these measures do not provide access to previous versions of files.

Distributions provide a wide range of backup tools, and leave it to the administrator to configure a suitable backup arrangement for their systems.

Resource Allocation Controls

You may configure several mechanisms to limit the resources that an application or user account may consume. On systems with multiple users, enforce resource limits to ensure that no user may accidental or deliberately cause facilities to fail by using all of the available resources. Since the correct resource allocations vary widely, administrators must configure appropriate limits for the system.

To set resource limits for individual applications, add a ulimit setting to the shell script that launches them. For more information about about ulimit, refer to the manual for the bash shell:

info bash

The PAM login system includes a module to enforce certain resource limits for entire user sessions. The restrictions that this imposes may be circumvented, but they do provide some defence against accidental problems.

You must specifically enable storage quotas on each disk partition, if you require them. Quotas prevent users from overloading the storage and backup facilities, but quota management is often an administrative matter rather than a direct security concern. Configuring storage quotas is beyond the scope of this document.

Monitoring and Audit Facilities

On Linux systems, the syslog and klogd services record activity as it is reported by different parts of the system. The Linux kernel reports to klogd, whilst the other services and facilities on the system send log messages to a syslog service. Distributions provide several tools for reading and analyzing the system log files.

Several facilities on any UNIX-like system may also email reports and notifications directly to the root account, via the SMTP service. Edit the aliases file to redirect messages for root to another email address, and you will receive these emails at the specified address.

Automatic Log Summaries: Many distributions automatically send daily reports to the email address for root that summarize the activity logged by syslog and klogd.

To provide a central logging facility for your network, first select one of your systems as the log host. Configure the syslog services on your other systems to forward the information that they receive to the syslog service on the log host. You may then run analyzers on the log host to monitor events across the network.

For detailed real-time monitoring of the systems on your network, install SNMP agents that report to a management service such as Nagios or OpenNMS. SNMP is beyond the scope of this document.

Monitoring Network Appliances: Many network appliances, such as routers, support the syslog and SNMP standards. This enables you to monitor both UNIX systems and other network devices with the same log hosts and SNMP services.

Refer to the man page for basic information about syslogd:

man syslogd

Similarly, for more on klogd, refer to the man page:

man klogd

Both syslog and SNMP rely on software dispatching messages to a central service. If you configure process accounting on a system it maintains records of all the processes that are run on that system. Linux includes some support for process accounting, and distributions supply packages for GNU Accounting Utilities. Refer to the Web page for more information on the GNU Accounting Utilities:

http://www.gnu.org/software/acct/

Fedora and Red Hat Enterprise Linux systems also offer the LAuS (Linux Auditing System) framework. For more information on this, refer to the man pages for auditd:

man auditd

The System Firewall

The netfilter framework included in the Linux kernel restricts incoming and outgoing network connections according to a set of rules that have been defined by the administrator. Several Linux distributions configure firewall rules by default, and offer utilities for managing simple firewall configurations. You may also manage the firewall rules on any Linux system with the standard iptables and ip6tables command-line utilities, or with third-party utilities such as Firestarter. If you decide to use iptables, remember that it only configures restrictions for IP version 4 connections, and that you will need to use ip6tables to setup rules for IP version 6 as well.

Fedora, Mandriva, Red Hat, and SUSE automatically enable the firewall and supply their own graphical configuration utilities. You must manually configure and enable the firewall on Debian and Ubuntu systems. Current releases of Ubuntu include a command-line utility called ufw for firewall configuration.

Those Linux distributions that enable a firewall by default use a netfilter configuration that blocks connections from other systems. Any attempt by a remote system to access a service on a blocked port simply fails. This means that no other system may connect to an installed service, unless you specifically choose to unblock the relevant port.

Use Only One Means Of Managing Your Firewall: Every firewall utility modifies the current firewall rules on the system. To ensure that your firewall operates correctly, select one method of managing the configuration, and avoid editing the firewall rules by other means.

Application Isolation

The most common UNIX-like operating systems provide several methods of limiting the ability of a program to affect either other running programs, or the host system itself.

Mandatory Access Control (MAC) supplements the normal UNIX security facilities of a system by enforcing absolute limits that cannot be circumvented by any program or account.
Virtualization enables you to assign a limited set of hardware resources to a virtual machine, which may be monitored and backed up by separate processes on the host system.
The chroot utility runs programs within a specified working directory, and prevents them from accessing any other directory on that system.

The administrator may setup guest operating systems in virtual environments for specific tasks, and restrict these guests far more than would be possible for a multi-purpose system. Each specialized system may include far less software, and this also simplifies every administrative task, including MAC configuration. Neither MAC nor virtualization prevent individual applications or services from being compromised, misconfigured or malfunctioning, but may prevent a problem from escalating.

At the simplest level, the SELinux framework can provide MAC facilities, to enforce a policy that defines the access permitted to programs or accounts on the system. SELinux was actually created by the NSA to meet the needs of government agencies handling classified data, and enables administrators to develop extremely detailed and precise security configurations that encompass the entire operating system. Many developers and administrators consider SELinux too high a maintenance burden to implement fully.

Fedora and Red Hat Enterprise Linux systems automatically include a limited SELinux policy that restricts many standard network services, without affecting users or other programs. These distributions also provide some simple management tools for customizing the default policy and troubleshooting SELinux issues, but no tools to assist with developing new policies.

Ubuntu, SUSE, and Mandriva do not enable SELinux by default. Instead, they provide the AppArmor facility. AppArmor configuration is much simpler than SELinux, but it offers more limited capabilities.

Several Open Source solutions exist to run complete operating systems within a virtual environment. By far the most popular are are Xen and KVM. Xen enables you to configure a system to act as a host for multiple virtual environments, all of which are controlled by a single hypervisor. Current Linux distributions on machines that include CPUs with virtualization support may run the simpler and more flexible KVM. The current KVM offers significantly higher performance than the QEMU machine emulator that is it based upon. The original QEMU software operates too slowly for production applications, although it remains useful for testing and development work.

The older chroot facility is universally available, but was originally designed for development tasks rather than security, and may be circumvented. Developers use this facility for building and testing software in a clean environment. Historically, administrators also used chroot to run potentially unsafe network services such as FTP servers within specially designed environments. Several tools exist to simplify constructing and maintaining chroot environments.

Applications May Escape chroot: Any application that is able to run arbitrary commands can execute code to gain access to the main system. To ensure the security of the chroot environment, avoid including shells, compilers, or script interpreters within the chroot directory. Any application that runs with root privileges may also escape the restrictions of chroot.

For more information about chroot, refer to the manual:

info chroot

A Note on Viruses and Malware

The security features of UNIX-like systems described above combine to form a strong defense against malware:

Software is often supplied in the form of packages, rather than programs
If you download a working program, it cannot run until you choose to mark the files as executable
By default, applications such as the OpenOffice.org suite and the Evolution email client do not run programs embedded in emails or documents
Web browsers require you to approve the installation of plug-ins
Software vulnerabilities can be rapidly closed by vendors supplying updated packages to the repositories

Although a virus could be written for use against current UNIX-like systems, no effective malware is known to exist. It is likely that any future malware would need the consent of a user on the system in order to install itself, significantly reducing the possibility that any such software would be able to spread across networks.

Installing Ruby

2011-02-06T17:49:00Z

Installing Ruby itself is quick and easy, but this page also covers a few additional steps that are needed for an ideal Ruby 1.8 environment:

Installing a C compiler, so that RubyGems can compile native extensions for the gems that you install.
Ensuring that the installed copy of RubyGems package manager is at least version 1.3.6, so that third-party libraries and frameworks install correctly.
Setting up a private gem directory within your home directory, so that you can add and remove gems without any risk of disrupting the system copy of Ruby.

The installation notes for Linux were adapted from posts on Hackido and Coding in the Rain.

Installing Ruby on Linux

All of the Linux distributions provide packages for Ruby. Ubuntu and other Debian-based systems split Ruby into multiple packages, so you need to specify several packages to get the complete set. To install Ruby on Ubuntu, enter the following command:

sudo apt-get install ruby irb rdoc ruby-dev libopenssl-ruby libreadline-ruby

The Debian and Ubuntu distributions also provide packages of example code:

sudo apt-get install ruby1.8-examples

Once the package is installed, check /usr/share/doc/ruby1.8-examples/ for the example scripts.

Installing a C Compiler

Run this command to install a C compiler:

sudo apt-get install build-essential

Installing RubyGems

Download RubyGems directly from the RubyForge Web site. Vendor packages for RubyGems are always out of date, as new versions of RubyGems are released quite frequently.

wget http://rubyforge.org/frs/download.php/70696/rubygems-1.3.7.tgz
tar xvzf rubygems-1.3.7.tgz
cd rubygems-1.3.7
sudo ruby setup.rb

On Ubuntu and other Debian-based systems, run this command to register gem1.8 with the alias gem:

sudo update-alternatives --install /usr/bin/gem gem /usr/bin/gem1.8 1

Finally, run this command to test that everything is working as it should:

gem --version

You may delete the tar (.tgz) file and the uncompressed directory once you have run the setup script.

Install Gems To Your Home Directory: This ensures that RubyGems installs and updates packages to your home directory, leaving the system copies untouched.

Recommended: Installing Gems to Your Home Directory

Where possible, avoid installing gems into the global system. This ensures that the gems that you install are easy to identify and manage, and do not interfere with the global Ruby installation.

As of RubyGems 1.3, RubyGems will automatically install gems into the directory specified by the GEM_HOME environment variable if the system location is not accessible. You will see that directories are created within your GEM_HOME directory to store gem files. This means that RubyGems will do the right thing when managing packages, provided that you do not run the gem utility with administrative privileges.

To do this, edit the .profile file in your home directory, and add or amend it to include these lines:

export GEM_HOME=$HOME/gems
export PATH=$GEM_HOME/bin:$PATH

This takes effect the next time that you login or create a terminal window.

The presence of the bin subdirectory on your PATH enables you to use any command-line utilities that are installed with your gem packages.

Installing SQLite on Linux for Ruby

To use the default Ruby on Rails configuration and other applications that depend upon SQLite, you need to install it separately. On Ubuntu and Debian-like systems, run this command to install SQLite:

sudo apt-get install libsqlite3-dev sqlite3

Then install the Ruby driver for SQLite:

gem install sqlite3-ruby

Ruby on Microsoft Windows

To install Ruby on Windows, first go to the RubyInstaller project Website. Download both the RubyInstaller and the Development Kit. The Development Kit provides a C compiler. Ignore the One-Click Installer options, as the One-Click Installer has been superseded by the RubyInstaller.

Run the Ruby Installer, and accept the defaults. This automatically installs RubyGems. Follow the instructions to setup the Development Kit.

You need to have an archive utility installed, as Windows does not include support for the 7Zip format used to compress the Development Kit.

Enabling Ruby and RubyGems to Work with an NTLM Web Proxy

To enable your Ruby installation with work with web proxy servers that require Windows authentication (known as NTLM authentication), use rubysspi. This package includes several features to allow RubyGems and Ruby standard libraries to use such proxy servers.

If RubyGems is not able to fetch gem packages at this point, use your Web browser to download the rubysspi gem to your hard drive. Run the gem utility, specifying the full name of the downloaded package file. For example:

gem install rubysspi-1.3.1.gem

To enable RubyGems to work with NTLM proxies, simply install the gem and copy the file spa.rb from the package directory (e.g. C:\Ruby\lib\ruby\gems\1.8\gems\rubysspi-1.3.1) to the Ruby site directory, which is C:\Ruby\lib\ruby\site_ruby\1.8 for Ruby 1.8.

copy C:\Ruby\lib\ruby\gems\1.8\gems\rubysspi-1.3.1\spa.rb C:\Ruby\lib\ruby\site_ruby\1.8

RubyGems will then use remote servers as normal, transparently logging on to the default proxy server for the Windows installation with the credentials of the logged-in user. To set the default proxy server, go to Start > Control Panel > Network and Internet > Internet Options > Connections > LAN Settings.

Installing SQLite on Windows for Ruby

To use the default Ruby on Rails configuration and other applications that depend upon SQLite, you need to install it separately. Luis Lavena provides full instructions for setting up Rails and SQLite on Windows.

Alternatively, you can use Amalgalite, which provides SQLite as a Ruby library. Install the ActiveRecord adapter for Amalgalite to use Amalgalite with Ruby on Rails.

Ruby on Mac OS X

Current versions of Mac OS X include Ruby, along with Rails and supporting libraries. To install a C compiler, run the XCode Tools setup. The XCode Tools package is on the OS X Install DVD provided with current Macs, in the Optional Installs folder.

Adding a Linux Server to an Active Directory Domain

2011-02-06T17:46:00Z

These notes were written for a Fedora system, which is closely related to Red Hat Enterprise Linux and CentOS, but the software described is available for every Open Source operating system.

Privileged Commands: The prefix # indicates commands that require root privileges.

Introduction

Integrating a Linux server with an Active Directory consists of several steps, and is not difficult if one simply follows the instructions for each step. The main difficulty is in understanding what each system does.

PAM is a flexible authentication system that is now incorporated into most UNIX variants. When any PAM-aware service is presented with a username and password, then these are simply passed on to PAM. PAM can be configured to consult multiple information sources and perform various other actions as part of the login process.

Kerberos is a technical standard that enables secure communication between all users and systems that are part of a single Kerberos realm. Each Kerberos KDC service for a realm has a copy of the database that holds user and system records. Several providers offer server software that implements Kerberos, and Microsoft Active Directory is one such product.

There are several similarities between Kerberos and LANMAN, the authentication technology used by Windows NT 4.0. A Kerberos realm equates to an NT domain, and KDC servers hold copies of the accounts database just as LANMAN domain controllers did. With Windows 2000 and above a Windows (Active Directory) domain actually is a Kerberos realm, the domain controllers are Kerberos Key Distribution Centers for that realm, and the client systems use the Kerberos protocol to authenticate users with the domain controller servers. To ease the transition, Microsoft continue to use LANMAN terminology, and Active Directory domain controllers act as both LANMAN domain controllers, and KDCs.

LANMAN clients automatically located a domain controller by querying the network WINS service. Kerberos KDCs have special SRV records in DNS, and the clients query DNS to find an available server to authenticate with. Active Directory automatically injects SRV records for the domain controllers into Microsoft DNS zones.

Samba is a suite of software for UNIX-like systems that handles file sharing, printer sharing and logons in a Windows-compatible way. The main Samba service provides the functions of Windows File and Printer sharing (technically known as SMB or CIFS), and may also act as a LANMAN domain controller.

The Samba suite provides a separate Winbind service that supports both PAM and the main Samba service. When a user attempts to login to a server running Winbind then PAM or the Samba service may call it to verify the account with a remote domain controller. Winbind works with both NT 4.0 domains and Active Directory domains.

UNIX-like systems store information about users differently to Windows, and this means that even if a user is listed in Active Directory then Samba must have some information about the user account in it’s own database. Equally, having a user account on a UNIX-like system does not allow the user to access files and printers through the Samba service unless the user has a listing in the Samba user database.

Prerequisites

Samba 3 is needed for a UNIX-like system to join Active Directory as a full member server. This version is now included with every current Open Source operating system.

On a Fedora or Red Hat system, install the following packages:

Samba:

redhat-config-samba
samba-common
samba-client
samba

Kerberos:

pam_krb5
krb5-workstation
krb5-libs
krbafs

Before starting this process, ensure that the Linux system is networking correctly, and has a valid entry in DNS. Also ensure that you know:

The DNS name of a DC server.
An Active Directory username and password that has the right to add machines to the Active Directory.
The Organizational Unit (OU) that you want the Linux server to be listed in.

If your network still uses WINS then you also need to know the IP address of the WINS server (it’s probably the DC that is configured with the PDC emulator role).

Documentation

Samba includes a very complete set of documentation. The relevant sections are in the Samba HOWTO:

Joining Active Directory As A Member Server (Chapter 7)
Synchronising Accounts with Winbind (Chapter 21)

For PAM the documentation is here:

/usr/share/doc/pam-0.77/html/index.html

This walk-through was also very useful for me:

http://www.flatmtn.com/computer/Linux-EmailServer.html

Configure Kerberos

Samba 3 uses the Kerberos protocol to authenticate with Active Directory, so you need to configure the Linux system to act as a Kerberos client for the realm (domain) for this facility to work. Fedora supplies the MIT Kerberos software. If the krb5-workstation package has been installed then the necessary client programs will be in /usr/kerberos/bin/.

The name of the Active Directory Kerberos realm is the same as it’s domain name. Usernames are also the same, but are suffixed with the name of the realm that they are part of. In standard Kerberos all names are in upper case, e.g.

MROBERTS@ADEXAMPLE.LOCAL

Active Directory domain controllers are registered in DNS, so you do not need to manually specify the servers. Instead edit /etc/krb5.conf to enable DNS lookups. The libdefaults section should read:

[libdefaults]
ticket_lifetime = 24000
default_realm = ADEXAMPLE.LOCAL
dns_lookup_realm = yes
dns_lookup_kdc = yes

Comment out the realms and domain_realms sections.

To test that Kerberos is configured correctly, use the kinit command:

kinit MROBERTS@ADEXAMPLE.LOCAL

Configure Samba

The supplied Samba configuration file is very long, and most of the settings are not necessary for AD membership. Make a copy of the file and create a blank one:

# cp /etc/samba/smb.conf /samba/smb.conf.original

An example smb.conf for an Active Directory member server:

[global]

socket options = TCP_NODELAY
SO_RCVBUF=8192
SO_SNDBUF=8192

workgroup = ADEXAMPLE
server string = Samba Server

local master = no
domain master = no
preferred master = no
wins support = no
wins server = 10.0.1.2
dns proxy = no

realm = ADEXAMPLE.LOCAL
security = ADS

password server = ms-dc-01.adexample.local

winbind separator = +
winbind use default domain = yes
idmap uid = 10000-20000
idmap gid = 10000-20000
winbind enum users = yes
winbind enum groups = yes

template homedir = /home/%U
template shell = /bin/nologin

log file = /var/log/samba/%m.log
max log size = 5000

printcap name = /etc/printcap
load printers = no

If you want the main Samba service to provide access to home directories or printers, add these stanzas. For printer sharing you should also change load printers = no to read load printers = yes.

[homes]
comment = Home Directories
browseable = no
writable = yes

[printers]
comment = All Printers
path = /var/spool/samba
browseable = no
guest ok = no
writable = no
printable = yes

Once you have edited the smb.conf file, run the testparm utility to check that the Samba configuration is valid:

# testparm

Add the System to Active Directory

First you must login to the Active Directory with kinit, since no other method has been setup yet:

# kinit USER@ADEXAMPLE.LOCAL

You may then use the net utility to create a machine account for the new member server:

# net ads join "Example-OU\Example-OU"

Configure Winbind

Once Samba is configured you must set the nsswitch system to use Winbind to verify accounts that do not exist on the local system. In the file /etc/nsswitch.conf amend the lines:

passwd:     files
shadow:     files
group:      files

To read:

passwd:     files winbind
shadow:     files
group:      files winbind

Winbind has better performance when run in double daemon mode. In the file /etc/sysconfig/samba amend the line:

WINBINDOPTIONS=""

To read:

WINBINDOPTIONS="-B"

Disable NSCD

The service NSCD (Name Service Caching Daemon) seriously interferes with Winbind authentication and must be completely disabled before enabling Winbind.

To do this, edit /etc/nscd.conf. Edit these three lines:

enable-cache            passwd          yes
enable-cache            group           yes
enable-cache            hosts           yes

They should read:

enable-cache            passwd          no
enable-cache            group           no
enable-cache            hosts           no

This disables all NSCD caching.

To make the new configuration active, restart the network service:

# /sbin/service network restart

Configure Services To Use Winbind

The PAM configuration for Samba itself does not need to be modified for Winbind. By default the main Samba service ignores PAM, and will either use Winbind or an internal account database to authenticate users.

Most other modern services on Linux use the PAM system for authentication. If you want to use Winbind with every service on the system that supports PAM, then modify /etc/pam.d/system-auth. If you only want specific services to use Winbind for authentication then you need to modify individual configuration files in /etc/pam.d/. Several services have their own file, but a number of services use the login facility, controlled by /etc/pam.d/login.

Add two lines to the appropriate PAM file:

auth sufficient /lib/security/pam_winbind.so

and

account sufficient /lib/security/pam_winbind.so

Amend all other auth and account types from required to sufficient.

Note that PAM reads the file sequentially, so where there are multiple sufficient sources the first successful one is used. Think carefully about the sequence in which you wish the system to check authentication services. A laptop may be off the main network more often than it is on it, and will be unable to access internal authentication services whilst it is disconnected.

If you edit the PAM configuration file for a service, you must restart that service for the changes to take effect.

Default /etc/pam.d./sshd settings:

auth      required     pam_stack.so service=system-auth
auth      required     pam_nologin.so
account   required     pam_stack.so service=system-auth
password  required     pam_stack.so service=system-auth
session   required     pam_stack.so service=system-auth
session   required     pam_limits.so
session   optional     pam_console.so

Example /etc/pam.d/sshd using Winbind:

auth      required     pam_nologin.so
auth      sufficient   pam_stack.so service=system-auth
auth      sufficient   pam_winbind.so

account    sufficient  pam_stack.so service=system-auth
account    sufficient  pam_winbind.so

password  required     pam_stack.so service=system-auth

session    sufficient  pam_stack.so service=system-auth
session   required     pam_limits.so
session   optional     pam_console.so

PAM does not guarantee that the user will have a home directory available, and without one the login process will fail. If you want to automatically use a home directory stored on another server, investigate automount.

If you would like to automatically create local home directories for new users as they login, then you could use this line in the PAM configuration:

session required pam_mkhomedir.so skel=/etc/skel/ umask=0022

If at all possible, create any local home directories with another means, before the user concerned can sign in. The easiest way may be to add the facility to your account creation scripts. By default SSH (and an increasing number of other services) do not run with root privileges through the login process, which means that they cannot create home directories as pam_mkhomedir.so mandates. Forcing services to run as root is not recommended.

Enable the Services

You can start the main smb service for Samba by typing:

# /sbin/service smb start

To make the smb service automatically start on boot:

# /sbin/chkconfig --level 345 smb on

To run Winbind:

# /sbin/service winbind start

To make Winbind automatically start on boot:

# /sbin/chkconfig --level 345 winbind on

The main Samba service does not need to be running for Winbind to operate.

Tip: Username Formats

Kerberos usernames use this format, and must be in uppercase:

AUSER@ADEXAMPLE.LOCAL

Winbind usernames have the format:

ADEXAMPLE+auser

If you enable the setting winbind use default domain (as shown in the example smb.conf above), users may just specify an account name:

auser