README copyedits

README copyedits

= Asciidoctor Extensions Lab
:idprefix:
:idseparator: -
:toc: preamble

A repository of sample and incubating Ruby-based extensions for Asciidoctor.

If you simply want to use the extensions in this repository, skip ahead to <<using-an-extension>>.
To create your own extension, we recommend that you first read the http://asciidoctor.org/docs/user-manual/#extensions[extensions section] in the Asciidoctor user manual.

== Extension types

We have the following types of extensions in the lab:

- *Preprocessor* - processes the AsciiDoc source before it is parsed
- *IncludeProcessor* - intercepts the AsciiDoc include directive
- *Treeprocessor* - processes the parsed AsciiDoc document (AST)
- *Postprocessor* - processes the converted output before it is written to the output stream (or disk)
- *BlockProcessor* - adds a custom delimited block
- *BlockMacroProcessor* - adds a custom block macro
- *InlineMacroProcessor* - adds a custom inline macro

The type of extension (e.g, `-block-macro`) is always used in the name of the extension registration file and directory to make it easy to distinguish.
You can also look for examples using `git grep`.
For example, to look for a `BlockMacroProcessor`, run the following command:

  $ git grep BlockMacroProcessor lib/

You'll get a result like this:

....
lib/chart-block-macro/extension.rb:class ChartBlockMacro < Extensions::BlockMacroProcessor
lib/gist-block-macro/extension.rb:class GistBlockMacro < Extensions::BlockMacroProcessor
lib/pass-block-macro/extension.rb:class PassBlockMacro < Extensions::BlockMacroProcessor
lib/tree-block-macro/extension.rb:class TreeBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
....

== Extension files

Each extension consists of several files:

- A file that registers the extension (sometimes also contains the extension)
- A file with the extension itself (when not defined in the registration file)
- A file with sample AsciiDoc source to use to test the extension
- Auxiliary assets needed by the extension

For example, the emoji-inline-macro extension has four files:

- https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro.rb[lib/emoji-inline-macro.rb] (registration file)
- https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/extension.rb[lib/emoji-inline-macro/extension.rb] (extension file)
- https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/sample.adoc[lib/emoji-inline-macro/sample.adoc] (sample AsciiDoc file)
- https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/twemoji-awesome.css[lib/emoji-inline-macro/twemoji-awesome.css] (auxiliary asset file)

NOTE: The registration file (e.g., emoji-inline-macro.rb) goes in the [path]_lib_ directory whereas the remaining files go inside a directory whose base name matches the name of the registration file (e.g., emoji-inline-macro).

== Extension catalog

The following extensions are available in the lab.

ChartBlockMacro, link:lib/chart-block-macro.rb[]::
Adds a chart block and block macro to AsciiDoc powered by c3js, chartist or chartjs.

ChromeInlineMacro, link:lib/chrome-inline-macro.rb[]::
Adds an inline macro for linking to a `chrome://` URI.

CopyrightFooterPostprocessor, link:lib/copyright-footer-postprocessor.rb[]::
Adds a copyright to the document footer based on the value of the `copyright` attribute.

EmojiInlineMacro, link:lib/emoji-inline-macro.rb[]::
Adds an emoji inline macro for inserting emoji by name.

FrontMatterPreprocessor, link:lib/front-matter-preprocessor.rb[]::
Emulates the built-in behavior of Asciidoctor to sweep away YAML front matter into the `front-matter` attribute.

GistBlockMacro, link:lib/gist-block-macro.rb[]::
Adds a block macro to embed a gist into an AsciiDoc document.

GoogleAnalyticsPostprocessor, link:lib/google-analytics-postprocessor.rb[]::
Adds the Google Analytics code for the account identified by the `google-analytics-account` attribute to the end of the HTML document.

HardbreaksPreprocessor, link:lib/hardbreaks-preprocessor.rb[]::
Adds hardbreaks to the end of all non-empty lines that aren't section titles.

ImplicitApidocInlineMacro, link:lib/implicit-apidoc-inline-macro.rb[]::
Adds an inline macro for linking to the Javadoc of a class in the Java EE API.

LicenseUrlDocinfoProcessor, link:lib/license-url-docinfoprocessor.rb[]::
Adds a link to the license specified by the `license` attribute to the document header.

ManInlineMacro, link:lib/man-inline-macro.rb[]::
Adds an inline macro for linking to another man page (used in the Git documentation).

MathematicalTreeprocessor, link:lib/mathematical-treeprocessor.rb[]::
Converts all latexmath blocks to SVG using the Mathematical library.

MathoidTreeprocessor, link:lib/mathoid-treeprocessor.rb[]::
Converts all stem blocks to SVG using MathJax via the Mathoid library.

MentionsInlineMacro, link:lib/mentions-inline-macro.rb[]::
Detects Twitter-style username mentions and converts them to links.

PassBlockMacro, link:lib/pass-block-macro.rb[]::
Adds a pass block macro to AsciiDoc.

PickInlineMacro, link:lib/pick-inline-macro.rb[]::
Adds an inline macro for selecting between two values based on the value of another attribute.

PullquoteInlineMacro, link:lib/pullquote-inline-macro.rb[]::
Adds an inline macro to pull a quote out of the flow and display it in a sidebar.

SectnumoffsetTreeprocessor, link:lib/sectnumoffset-treeprocessor.rb[]::
Increments all level-1 section numbers (and subsequently all subsections) by the value of the `sectnumoffset` attribute.

ShellSessionTreeprocessor, link:lib/shell-session-treeprocessor.rb[]::
Detects a shell command and trailing output and styles it for display in HTML.

ShoutBlock, link:lib/shout-block.rb[]::
Converts all text inside a delimited block named `shout` to uppercase and adds trailing exclamation marks.

ShowCommentsPreprocessor, link:lib/showcomments-preprocessor.rb[]::
Converts line comments to visual elements (normally dropped).

SlimBlock, link:lib/slim-block.rb[]::
Passes the content in blocks named `slim` to the Slim template engine for processing.

StepsPostprocessor, link:lib/steps-postprocessor.rb[]::
Styles an ordered list as a procedure list.

TexPreprocessor, link:lib/tex-preprocessor.rb[]::
Interprets tex markup embedded inside of AsciiDoc.

TextqlBlock, link:lib/textql-block.rb[]::
Adds a block for using textql to process data in an AsciiDoc document.

TreeBlockMacro, link:lib/tree-block-macro.rb[]::
Adds a block macro to show the output of the `tree` command.

UndoReplacementsPostprocessor, link:lib/undo-replacements-postprocessor.rb[]::
Reverses the text replacements that are performed by Asciidoctor.

UriIncludeProcessor, link:lib/uri-include-processor.rb[]::
Emulates the built-in behavior of Asciidoctor to include content from a URI.

ViewResultPostprocessor, link:lib/view-result-postprocessor.rb[]::
Adds an interactive toggle to block content marked as a view result.

WhitespaceIncludeProcessor, link:lib/whitespace-include-processor.rb[]::
An include processor that substitutes tabs with spaces (naively) in included source code.

XmlEntityPostprocessor, link:lib/xml-entity-postprocessor.rb[]::
Converts named entities to character entities so they can be resolved without the use of external entity declarations.

//^

== Using an extension

Before creating your own extensions, it would be wise to run one yourself.
First, make sure Asciidoctor is installed:

 $ gem install asciidoctor

Next, run the extension from the root directory of the project:

  $ asciidoctor -r lib/emoji-inline-macro.rb lib/emoji-inline-macro/sample.adoc
  # asciidoctor: FAILED: 'lib/emoji-inline-macro.rb' could not be loaded
  # Use --trace for backtrace

Oops!
We forgot to include the leading `./` when using the `-r` flag
Let's try again:

  $ asciidoctor -r ./lib/emoji-inline-macro.rb lib/emoji-inline-macro/sample.adoc

All right, it ran!
The output file, [path]_sample.html_, was created in the same directory as the source file, [path]_sample.adoc_.

The relevant bits of the input and output are shown below.

._lib/emoji-inline-macro/sample.adoc_
```asciidoc
Faster than a emoji:turtle[1x]!

This is an example of how you can emoji:heart[lg] Asciidoctor and Twitter Emoji.
```

._lib/emoji-inline-macro/sample.html_
```html
<div class="paragraph">
<p>Faster than a <i class="twa twa-1x twa-turtle"></i>!</p>
</div>
<div class="paragraph">
<p>This is an example of how you can <i class="twa twa-lg twa-heart"></i> Asciidoctor and Twitter Emoji.</p>
</div>
```

WARNING: Certain extensions require additional libraries.
Please consult the extension's registration file for details about what is required to use it.

== Adding an extension

You can find examples of various ways to define an extension in the link:lib/shout-block.rb[] extension.

=== Shorthand (DSL)

If you're creating a trivial extension, you can define the extension using the extension DSL directly in the registration file.
Create a new file in the [path]_lib_ directory.
Include the extension type in the name of the file so others are clear what type of extension it is.

._lib/sample-block.rb_
```ruby
require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'

include Asciidoctor

Extensions.register do
  block do
    named :sample
    on_context :open

    process do |parent, reader, attrs|
      create_paragraph parent, reader.lines, attrs
    end
  end
end
```

TIP: The `include Asciidoctor` line allows you to use classes from Asciidoctor without the `Asciidoctor::` prefix.

=== Formal

If you're creating a more complex extension or want to enable reuse, you're encouraged to move the extension code to the [path]_extension.rb_ inside a directory with the same base name as the registration file.
In the case of a block, block macro or inline macro, this enables you to register the extension multiple times.

._lib/sample-block.rb_
```ruby
RUBY_ENGINE == 'opal' ? (require 'sample-block/extension') : (require_relative 'sample-block/extension')

Extensions.register do
  block SampleBlock
end
```

._lib/sample-block/extensions.rb_
```ruby
class SampleBlock < Extensions::BlockProcessor
  use_dsl
  named :sample
  on_context :open

  def process parent, reader, attrs
    create_paragraph parent, reader.lines, attrs
  end
end
```

It's customary to provide a sample AsciiDoc file named [path]_sample.adoc_ inside the extension subdirectory that others can use to try the extension.
You should also add your extension to the <<extension-catalog>> section along with a short description of what it does.

== Other extensions

See http://asciidoctor.org/docs/extensions/[this list] of extensions for Asciidoctor.

////
== Transpiling extensions for Asciidoctor.js

https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/44[TODO].
////

= Asciidoctor Extensions Lab
:idprefix:
:idseparator: -
:toc: preamble

A repository of sample and incubating Ruby-based extensions for Asciidoctor.

If you just want to use the extensions here, skip ahead to <<using-an-extension>>.
To create your own extension, we recommend that you first read the http://asciidoctor.org/docs/user-manual/#extensions[extensions section] in the Asciidoctor user manual.

== Extension types

We have these types of extensions in the lab:

- *Preprocessor* - processes the AsciiDoc source before it is parsed
- *IncludeProcessor* - intercepts the AsciiDoc include directive
- *Treeprocessor* - processes the parsed AsciiDoc document (AST)
- *Postprocessor* - processes the converted output before it is written to the output stream (or disk)
- *BlockProcessor* - adds a custom delimited block
- *BlockMacroProcessor* - adds a custom block macro
- *InlineMacroProcessor* - adds a custom inline macro

The type of extension (e.g, `-block-macro`) is always used in the name of the extension load file and directory to make it easy to distinguish.
You can also look for examples using `git grep`.
For example, to look for a `BlockMacroProcessor`, run the following command:

  $ git grep BlockMacroProcessor lib/

You will get a result like this:

....
lib/chart-block-macro/extension.rb:class ChartBlockMacro < Extensions::BlockMacroProcessor
lib/gist-block-macro/extension.rb:class GistBlockMacro < Extensions::BlockMacroProcessor
lib/pass-block-macro/extension.rb:class PassBlockMacro < Extensions::BlockMacroProcessor
lib/tree-block-macro/extension.rb:class TreeBlockMacro < Asciidoctor::Extensions::BlockMacroProcessor
....

== Extension files

Each extension consists of several files:

- A file that registers the extension (sometimes also contains the extension)
- A file with the extension itself (when not defined in the registration file)
- A file with sample AsciiDoc source to use to test the section
- Auxiliary assets needed by the extension

For example, the emoji-inline-macro extension has four files:

- https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro.rb[lib/emoji-inline-macro.rb] (registration file)
- https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/extension.rb[lib/emoji-inline-macro/extension.rb] (extension file)
- https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/sample.adoc[lib/emoji-inline-macro/sample.adoc] (sample AsciiDoc file)
- https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/emoji-inline-macro/twemoji-awesome.css[lib/emoji-inline-macro/twemoji-awesome.css] (auxiliary asset file)

NOTE: The registration file (e.g., emoji-inline-macro.rb) goes in the [path]_lib_ directory whereas the remaining files go inside a directory whose base name matches the name of the registration file (e.g., emoji-inline-macro).

== Extension catalog

The following extensions are available in the lab.

ChartBlockMacro, link:lib/chart-block-macro.rb[]::
Adds a chart block and block macro to AsciiDoc powered by c3js, chartist or chartjs.

ChromeInlineMacro, link:lib/chrome-inline-macro.rb[]::
Adds an inline macro for linking to a `chrome://` URI.

CopyrightFooterPostprocessor, link:lib/copyright-footer-postprocessor.rb[]::
Adds a copyright to the document footer based on the value of the `copyright` attribute.

EmojiInlineMacro, link:lib/emoji-inline-macro.rb[]::
Adds an emoji inline macro for inserting emoji by name.

FrontMatterPreprocessor, link:lib/front-matter-preprocessor.rb[]::
Emulates the built-in behavior of Asciidoctor to sweep away YAML front matter into the `front-matter` attribute.

GistBlockMacro, link:lib/gist-block-macro.rb[]::
Adds a block macro to embed a gist into an AsciiDoc document.

GoogleAnalyticsPostprocessor, link:lib/google-analytics-postprocessor.rb[]::
Adds the Google Analytics code for the account identified by the `google-analytics-account` attribute to the end of the HTML document.

HardbreaksPreprocessor, link:lib/hardbreaks-preprocessor.rb[]::
Adds hardbreaks to the end of all non-empty lines that aren't section titles.

ImplicitApidocInlineMacro, link:lib/implicit-apidoc-inline-macro.rb[]::
Adds an inline macro for linking to the Javadoc of a class in the Java EE API.

LicenseUrlDocinfoProcessor, link:lib/license-url-docinfoprocessor.rb[]::
Adds a link to the license specified by the `license` attribute to the document header.

ManInlineMacro, link:lib/man-inline-macro.rb[]::
Adds an inline macro for linking to another man page (used in the Git documentation).

MathematicalTreeprocessor, link:lib/mathematical-treeprocessor.rb[]::
Converts all latexmath blocks to SVG using the Mathematical library.

MathoidTreeprocessor, link:lib/mathoid-treeprocessor.rb[]::
Converts all stem blocks to SVG using MathJax via the Mathoid library.

MentionsInlineMacro, link:lib/mentions-inline-macro.rb[]::
Detects Twitter-style username mentions and converts them to links.

PassBlockMacro, link:lib/pass-block-macro.rb[]::
Adds a pass block macro to AsciiDoc.

PickInlineMacro, link:lib/pick-inline-macro.rb[]::
Adds an inline macro for selecting between two values based on the value of another attribute.

PullquoteInlineMacro, link:lib/pullquote-inline-macro.rb[]::
Adds an inline macro to pull a quote out of the flow and display it in a sidebar.

SectnumoffsetTreeprocessor, link:lib/sectnumoffset-treeprocessor.rb[]::
Increments all level-1 section numbers (and subsequently all subsections) by the value of the `sectnumoffset` attribute.

ShellSessionTreeprocessor, link:lib/shell-session-treeprocessor.rb[]::
Detects a shell command and trailing output and styles it for display in HTML.

ShoutBlock, link:lib/shout-block.rb[]::
Converts all text inside a delimited block named `shout` to uppercase and adds trailing exclamation marks.

ShowCommentsPreprocessor, link:lib/showcomments-preprocessor.rb[]::
Converts line comments to visual elements (normally dropped).

SlimBlock, link:lib/slim-block.rb[]::
Passes the content in blocks named `slim` to the Slim template engine for processing.

StepsPostprocessor, link:lib/steps-postprocessor.rb[]::
Styles an ordered list as a procedure list.

TexPreprocessor, link:lib/tex-preprocessor.rb[]::
Interprets tex markup embedded inside of AsciiDoc.

TextqlBlock, link:lib/textql-block.rb[]::
Adds a block for using textql to process data in an AsciiDoc document.

TreeBlockMacro, link:lib/tree-block-macro.rb[]::
Adds a block macro to show the output of the `tree` command.

UndoReplacementsPostprocessor, link:lib/undo-replacements-postprocessor.rb[]::
Reverses the text replacements that are performed by Asciidoctor.

UriIncludeProcessor, link:lib/uri-include-processor.rb[]::
Emulates the built-in behavior of Asciidoctor to include content from a URI.

ViewResultPostprocessor, link:lib/view-result-postprocessor.rb[]::
Adds an interactive toggle to block content marked as a view result.

WhitespaceIncludeProcessor, link:lib/whitespace-include-processor.rb[]::
An include processor that substitutes tabs with spaces (naively) in included source code.

XmlEntityPostprocessor, link:lib/xml-entity-postprocessor.rb[]::
Converts named entities to character entities so they can be resolved without the use of external entity declarations.

//^

== Using an extension

Before create your own extensions, it would be wise to run one yourself.
First, make sure Asciidoctor is installed:

 $ gem install asciidoctor

Next, we'll run an extension from the root directory of the project:

  $ asciidoctor -r lib/emoji-inline-macro.rb lib/emoji-inline-macro/sample.adoc
  # asciidoctor: FAILED: 'lib/emoji-inline-macro.rb' could not be loaded
  # Use --trace for backtrace

Oops!
We forgot to include the leading `./` when using the `-r` flag
Let's try again:

  $ asciidoctor -r ./lib/emoji-inline-macro.rb lib/emoji-inline-macro/sample.adoc

All right, it ran!
The output file, [path]_sample.html_, was created in the same directory as the source file, [path]_sample.adoc_.

The relevant bits of the input and output are show below.

._lib/emoji-inline-macro/sample.adoc_
```asciidoc
Faster than a emoji:turtle[1x]!

This is an example of how you can emoji:heart[lg] Asciidoctor and Twitter Emoji.
```

._lib/emoji-inline-macro/sample.html_
```html
<div class="paragraph">
<p>Faster than a <i class="twa twa-1x twa-turtle"></i>!</p>
</div>
<div class="paragraph">
<p>This is an example of how you can <i class="twa twa-lg twa-heart"></i> Asciidoctor and Twitter Emoji.</p>
</div>
```

WARNING: Certain extensions require additional libraries.
Please consult the registration file for the extension for details about what is required to use it.

== Adding an extension

You can find examples of various ways to define an extension in the link:lib/shout-block.rb[] extension.

=== Shorthand (DSL)

If you're creating a trivial extension, you can define the extension using the extension DSL directly in the registration file.
Create a new file in the [path]_lib_ directory.
Include the extension type in the name of the file so others are clear what type of extension it is.

._lib/sample-block.rb_
```ruby
require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'

include Asciidoctor

Extensions.register do
  block do
    named :sample
    on_context :open

    process do |parent, reader, attrs|
      create_paragraph parent, reader.lines, attrs
    end
  end
end
```

TIP: The `include Asciidoctor` line allows you to use classes from Asciidoctor without the `Asciidoctor::` prefix.

=== Formal

If you are creating a more complex extension or want to enable reuse, you are encouraged to move the extension code to the [path]_extension.rb_ inside a directory with the same base name as the registration file.
In the case of a block, block macro or inline macro extension, this enables you to register it multiple times.

._lib/sample-block.rb_
```ruby
RUBY_ENGINE == 'opal' ? (require 'sample-block/extension') : (require_relative 'sample-block/extension')

Extensions.register do
  block SampleBlock
end
```

._lib/sample-block/extensions.rb_
```ruby
class SampleBlock < Extensions::BlockProcessor
  use_dsl
  named :sample
  on_context :open

  def process parent, reader, attrs
    create_paragraph parent, reader.lines, attrs
  end
end
```

It's customary to provide a sample AsciiDoc file named [path]_sample.adoc_ inside the extension subdirectory that others can use to test the extension.
You should also add your extension to the <<extension-catalog>> section along with a short description of what it does.

== Other extensions

See http://asciidoctor.org/docs/extensions/[this list] of extensions for Asciidoctor.

////
== Transpiling extensions for Asciidoctor.js

https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/44[TODO].
////


mention Zapus

mention Zapus

Signed-off-by: Thomas Sjögren <9ff28d1cb1d19283ed3327b40df6c7d62d8bc343@users.noreply.github.com>

= Hardening Ubuntu. Systemd edition.
:icons: font

A quick way to make a Ubuntu server a bit more secure.

Tested on `15.10 Ubuntu Wily Werewolf`, `16.04 Xenial Xerus`, `16.10 Yakkety Yak` and `17.04 Zesty Zapus (development branch)`. +
Systemd required.

If you're just interested in the security focused systemd configuration, it's available as a link:systemd.adoc[separate document]. +
If you're interested in testing your host settings, you'll find the link:README.adoc#tests[instructions here]. +
If you're using Ansible, a playbook with most of the above functions implemented is available in my Ansible repository https://github.com/konstruktoid/Ansible[konstruktoid/Ansible].

NOTE: This is a constant work in progress. Make sure you understand what it does. Read the code.

== Howto
Start the installation of the server. +
Pick language, keyboard layout, timezone and so on as you usually would.

=== Partition the system
[source,shell]
----
/
/boot (rw)
/home (rw,nosuid,nodev)
swap
/var
/var/log (rw,nosuid,nodev,noexec)
/var/log/audit (rw,nosuid,nodev,noexec)
----

Note that `/tmp` and `/var/tmp` will be added automatically by the script.

=== Login, set a Grub2 password, configure and run ubuntu.sh
Do not add any packages. +
Log in. +
Select a Grub2 password (using `grub-mkpasswd-pbkdf2`). +
Download the script using `git clone https://github.com/konstruktoid/hardening.git`. +
Change the configuration options in the `ubuntu.cfg` file and last but not least run the script, `sudo bash ubuntu.sh`. +

== Configuration options
[source,shell]
----
FW_ADMIN='127.0.0.1' // <1>
SSH_GRPS='sudo' // <2>
SYSCTL_CONF='https://raw.githubusercontent.com/konstruktoid/hardening/master/misc/sysctl.conf' // <3>
AUDITD_RULES='https://raw.githubusercontent.com/konstruktoid/hardening/master/misc/audit.rules' // <4>
LOGROTATE_CONF='https://raw.githubusercontent.com/konstruktoid/hardening/master/misc/logrotate.conf' // <5>
NTPSERVERPOOL='0.ubuntu.pool.ntp.org 1.ubuntu.pool.ntp.org 2.ubuntu.pool.ntp.org 3.ubuntu.pool.ntp.org pool.ntp.org' // <6>
VERBOSE='N' // <7>
CHANGEME='' // <8>

# Configuration files
ADDUSER='/etc/adduser.conf'
AUDITDCONF='/etc/audit/auditd.conf'
AUDITRULES='/etc/audit/rules.d/hardening.rules'
COMMONPASSWD='/etc/pam.d/common-password'
COMMONACCOUNT='/etc/pam.d/common-account'
COMMONAUTH='/etc/pam.d/common-auth'
DEFAULTGRUB='/etc/default/grub'
DISABLEMNT='/etc/modprobe.d/disablemnt.conf'
DISABLEMOD='/etc/modprobe.d/disablemod.conf'
DISABLENET='/etc/modprobe.d/disablenet.conf'
JOURNALDCONF='/etc/systemd/journald.conf'
LIMITSCONF='/etc/security/limits.conf'
LOGINDCONF='/etc/systemd/logind.conf'
LOGINDEFS='/etc/login.defs'
LOGROTATE='/etc/logrotate.conf'
PAMLOGIN='/etc/pam.d/login'
RESOLVEDCONF='/etc/systemd/resolved.conf'
RKHUNTERCONF='/etc/default/rkhunter'
SECURITYACCESS='/etc/security/access.conf'
SSHDFILE='/etc/ssh/sshd_config'
SYSCTL='/etc/sysctl.conf'
SYSTEMCONF='/etc/systemd/system.conf'
TIMESYNCD='/etc/systemd/timesyncd.conf'
UFWDEFAULT='/etc/default/ufw'
USERADD='/etc/default/useradd'
USERCONF='/etc/systemd/user.conf'
----
<1> The IP addresses that will be able to connect with SSH.
<2> Which group the users have to be member of in order to acess via SSH.
<3> Stricter sysctl settings.
<4> Auditd rules.
<5> Logrotate settings.
<6> NTP server pool.
<7> If you want all the details or not.
<8> Add something just to verify that you actually glanced the code.

=== Function list
`pre` Script setup +
`firewall` Enable ufw and allow port 22 from `$FW_ADMIN` +
`disablenet` Disable misc network protocols +
`disablemnt` Disable misc file systems +
`disablemod` Disable misc kernel modules +
`resolvedconf` Systemd/resolved.conf +
`systemdconf` Systemd/system.conf and Systemd/user.conf +
`journalctl` Systemd/journald.conf and logrotate.conf +
`timesyncd` Systemd/timesyncd.conf +
`coredump` Systemd/coredump.conf +
`fstab` /etc/fstab, system/tmp.mount and system/var-tmp.mount +
`prelink` Prelink +
`aptget` Updating the package index and upgrading installed packages +
`hosts` /etc/hosts.allow and /etc/hosts.deny +
`issue` Add message to /etc/issue, /etc/issue.net, /etc/motd +
`logindefs` /etc/login.defs +
`logindconf` Systemd/logind.conf +
`sysctl` /etc/sysctl.conf +
`limitsconf` /etc/security/limits.conf +
`adduser` /etc/adduser.conf and /etc/default/useradd +
`rootaccess` /etc/security/access.conf and /etc/securetty +
`packages` Installing base packages +
`apport` Disable apport +
`rkhunter` Configures rkhunter +
`sshdconfig` /etc/ssh/sshd_config +
`password` /etc/pam.d/common-password and /etc/pam.d/common-auth +
`cron` /etc/cron and /etc/at +
`ctrlaltdel` Ctrl-alt-delete +
`auditd` Auditd +
`aide` Aide +
`rhosts` .rhosts +
`users` Remove users +
`lockroot` Lock root user account +
`aptget_clean` Remove unused packages +
`suid` Remove suid bits +
`umask` Set umask +
`path` Modify paths +
`aa_enforce` Enforce apparmor profiles +
`aide_post` Create Aide db +
`aide_timer` Enable daily Aide check +
`systemddelta` systemd-delta +
`checkreboot` Check if reboot is required

== Tests
There are approximately 275 https://github.com/sstephenson/bats[Bats tests] for most of the above settings available in the link:tests/[tests directory].

[source,shell]
----
git clone https://github.com/konstruktoid/hardening.git
cd tests/
sudo bats .
----

== Recommended reading
https://benchmarks.cisecurity.org/downloads/show-single/index.cfm?file=independentlinux.100[CIS Distribution Independent Linux Benchmark v1.0.0] +
http://iase.disa.mil/stigs/os/unix-linux/Pages/index.aspx[Draft Red Hat 7 STIG Version 1, Release 0.1] +
https://benchmarks.cisecurity.org/downloads/show-single/?file=ubuntu1404.100[CIS Ubuntu 14.04 LTS Server Benchmark v1.0.0] +
https://wiki.ubuntu.com/Security/Features +
https://help.ubuntu.com/community/StricterDefaults +

= Hardening Ubuntu. Systemd edition.
:icons: font

A quick way to make a Ubuntu server a bit more secure.

Tested on `15.10 Ubuntu Wily Werewolf`, `16.04 Xenial Xerus` and `16.10 Yakkety Yak`. +
Systemd required.

If you're just interested in the security focused systemd configuration, it's available as a link:systemd.adoc[separate document]. +
If you're interested in testing your host settings, you'll find the link:README.adoc#tests[instructions here]. +
If you're using Ansible, a playbook with most of the above functions implemented is available in my Ansible repository https://github.com/konstruktoid/Ansible[konstruktoid/Ansible].

NOTE: This is a constant work in progress. Make sure you understand what it does. Read the code.

== Howto
Start the installation of the server. +
Pick language, keyboard layout, timezone and so on as you usually would.

=== Partition the system
[source,shell]
----
/
/boot (rw)
/home (rw,nosuid,nodev)
swap
/var
/var/log (rw,nosuid,nodev,noexec)
/var/log/audit (rw,nosuid,nodev,noexec)
----

Note that `/tmp` and `/var/tmp` will be added automatically by the script.

=== Login, set a Grub2 password, configure and run ubuntu.sh
Do not add any packages. +
Log in. +
Select a Grub2 password (using `grub-mkpasswd-pbkdf2`). +
Download the script using `git clone https://github.com/konstruktoid/hardening.git`. +
Change the configuration options in the `ubuntu.cfg` file and last but not least run the script, `sudo bash ubuntu.sh`. +

== Configuration options
[source,shell]
----
FW_ADMIN='127.0.0.1' // <1>
SSH_GRPS='sudo' // <2>
SYSCTL_CONF='https://raw.githubusercontent.com/konstruktoid/hardening/master/misc/sysctl.conf' // <3>
AUDITD_RULES='https://raw.githubusercontent.com/konstruktoid/hardening/master/misc/audit.rules' // <4>
LOGROTATE_CONF='https://raw.githubusercontent.com/konstruktoid/hardening/master/misc/logrotate.conf' // <5>
NTPSERVERPOOL='0.ubuntu.pool.ntp.org 1.ubuntu.pool.ntp.org 2.ubuntu.pool.ntp.org 3.ubuntu.pool.ntp.org pool.ntp.org' // <6>
VERBOSE='N' // <7>
CHANGEME='' // <8>

# Configuration files
ADDUSER='/etc/adduser.conf'
AUDITDCONF='/etc/audit/auditd.conf'
AUDITRULES='/etc/audit/rules.d/hardening.rules'
COMMONPASSWD='/etc/pam.d/common-password'
COMMONACCOUNT='/etc/pam.d/common-account'
COMMONAUTH='/etc/pam.d/common-auth'
DEFAULTGRUB='/etc/default/grub'
DISABLEMNT='/etc/modprobe.d/disablemnt.conf'
DISABLEMOD='/etc/modprobe.d/disablemod.conf'
DISABLENET='/etc/modprobe.d/disablenet.conf'
JOURNALDCONF='/etc/systemd/journald.conf'
LIMITSCONF='/etc/security/limits.conf'
LOGINDCONF='/etc/systemd/logind.conf'
LOGINDEFS='/etc/login.defs'
LOGROTATE='/etc/logrotate.conf'
PAMLOGIN='/etc/pam.d/login'
RESOLVEDCONF='/etc/systemd/resolved.conf'
RKHUNTERCONF='/etc/default/rkhunter'
SECURITYACCESS='/etc/security/access.conf'
SSHDFILE='/etc/ssh/sshd_config'
SYSCTL='/etc/sysctl.conf'
SYSTEMCONF='/etc/systemd/system.conf'
TIMESYNCD='/etc/systemd/timesyncd.conf'
UFWDEFAULT='/etc/default/ufw'
USERADD='/etc/default/useradd'
USERCONF='/etc/systemd/user.conf'
----
<1> The IP addresses that will be able to connect with SSH.
<2> Which group the users have to be member of in order to acess via SSH.
<3> Stricter sysctl settings.
<4> Auditd rules.
<5> Logrotate settings.
<6> NTP server pool.
<7> If you want all the details or not.
<8> Add something just to verify that you actually glanced the code.

=== Function list
`pre` Script setup +
`firewall` Enable ufw and allow port 22 from `$FW_ADMIN` +
`disablenet` Disable misc network protocols +
`disablemnt` Disable misc file systems +
`disablemod` Disable misc kernel modules +
`resolvedconf` Systemd/resolved.conf +
`systemdconf` Systemd/system.conf and Systemd/user.conf +
`journalctl` Systemd/journald.conf and logrotate.conf +
`timesyncd` Systemd/timesyncd.conf +
`coredump` Systemd/coredump.conf +
`fstab` /etc/fstab, system/tmp.mount and system/var-tmp.mount +
`prelink` Prelink +
`aptget` Updating the package index and upgrading installed packages +
`hosts` /etc/hosts.allow and /etc/hosts.deny +
`issue` Add message to /etc/issue, /etc/issue.net, /etc/motd +
`logindefs` /etc/login.defs +
`logindconf` Systemd/logind.conf +
`sysctl` /etc/sysctl.conf +
`limitsconf` /etc/security/limits.conf +
`adduser` /etc/adduser.conf and /etc/default/useradd +
`rootaccess` /etc/security/access.conf and /etc/securetty +
`packages` Installing base packages +
`apport` Disable apport +
`rkhunter` Configures rkhunter +
`sshdconfig` /etc/ssh/sshd_config +
`password` /etc/pam.d/common-password and /etc/pam.d/common-auth +
`cron` /etc/cron and /etc/at +
`ctrlaltdel` Ctrl-alt-delete +
`auditd` Auditd +
`aide` Aide +
`rhosts` .rhosts +
`users` Remove users +
`lockroot` Lock root user account +
`aptget_clean` Remove unused packages +
`suid` Remove suid bits +
`umask` Set umask +
`path` Modify paths +
`aa_enforce` Enforce apparmor profiles +
`aide_post` Create Aide db +
`aide_timer` Enable daily Aide check +
`systemddelta` systemd-delta +
`checkreboot` Check if reboot is required

== Tests
There are approximately 275 https://github.com/sstephenson/bats[Bats tests] for most of the above settings available in the link:tests/[tests directory].

[source,shell]
----
git clone https://github.com/konstruktoid/hardening.git
cd tests/
sudo bats .
----

== Recommended reading
https://benchmarks.cisecurity.org/downloads/show-single/index.cfm?file=independentlinux.100[CIS Distribution Independent Linux Benchmark v1.0.0] +
http://iase.disa.mil/stigs/os/unix-linux/Pages/index.aspx[Draft Red Hat 7 STIG Version 1, Release 0.1] +
https://benchmarks.cisecurity.org/downloads/show-single/?file=ubuntu1404.100[CIS Ubuntu 14.04 LTS Server Benchmark v1.0.0] +
https://wiki.ubuntu.com/Security/Features +
https://help.ubuntu.com/community/StricterDefaults +


added documentation, usage and required var checking to script

:gitroot: https://github.com/markllama

== DNS Service for OpenStack with Heat

This repository defines a simple distributed DNS service within an
OpenStack Heat stack.  The goal is to de-mystify DNS services and
deployments for low level delegated sub-domains.  It is NOT to provide
enterprise scale and quality DNS services.

== Deployment Procedure

The stack is deployed using a set of Heat templates and an Ansible
playbook driven by a BASH script. In the future these will be
collapsed so the entire process is driven by Ansible.  For now a small
amount of glue code is still required.

=== Get the GIT repository

.Clone the Heat and Ansible repositories

[subs=attributes]
----
git clone {gitroot}/dns-service-heat.git
git clone {gitroot}/dns-service-playbooks.git
----

=== Input Values

ZONE::
  The DNS zone to be served +
  Type: string +
  Example: `example.com`

DNS_UPDATE_KEY::
  A symmetric key value for dynamic DNS updates +
  Type: string +
  This is a BASE64 encoded MD5 hash, randomly generated by
  `rndc-confgen(8)`.

SERVER_SPEC_FILE::
  The name of a YAML file containing the Nova instance specification values. +
  Example: +
----
parameters:
  flavor: m1.small
  image: rhel73
  ssh_user: cloud-user
----

EXTERNAL_NETWORK_NAME::
  The name of an existing Neutron network in the OSP environment which
  allows inbound and outbound traffic. +
  Type: string +
  Example: public_network

:gitroot: https://github.com/markllama

== DNS Service for OpenStack with Heat

This repository defines a simple distributed DNS service within an
OpenStack Heat stack.  The goal is to de-mystify DNS services and
deployments for low level delegated sub-domains.  It is NOT to provide
enterprise scale and quality DNS services.

== Deployment Procedure

The stack is deployed using a set of Heat templates and an Ansible
playbook driven by a BASH script. In the future these will be
collapsed so the entire process is driven by Ansible.  For now a small
amount of glue code is still required.

=== Get the GIT repository

.Clone the Heat and Ansible repositories

[subs=attributes]
----
git clone {gitroot}/dns-service-heat.git
git clone {gitroot}/dns-service-playbooks.git
----

=== Input Values

ZONE:
  The DNS zone to be served +
  Type: string
  Example: `example.com`

DNS_UPDATE_KEY::
  A symmetric key value for dynamic DNS updates +
  Type: string +
  This is a BASE64 encoded MD5 hash, randomly generated by
  `rndc-confgen(8)`.

SERVER_SPEC_FILE::
  The name of a YAML file containing the Nova instance specification values. +
  Example: +

----
parameters:
  flavor: m1.small
  image: rhel73
  ssh_user: cloud-user
----