Interactive system initialization

A configuration wizard shows a short sequence of simple text dialogs that look primitive but provide a quick step-by-step process that works anywhere and requires only the bare minimum of software dependencies - a big advantage for security sensitive applications:

All software is potentially buggy but we can minimize the risk by intentionally favoring simplicity over fancy eye candy.

The configuration dialogs run in one of two places:

1. The boot console on first boot on build types (e.g., ISO, VM, VMDK) where the real or virtual machine usually provides access to an interactive system console.

2. The first administration login on build types running on headless virtual machines (e.g., AWS marketplace, OpenStack, Xen). that don't provide the option to interact with the system at boot time.

   After boot, a virtual fence redirects attempts to access potentially vulnerable services to a web page explaining how to SSH into the machine for the first time to initialize the system. After initialization the virtual fence comes down and all services can be accessed normally.

Non-interactive system initialization

The TurnKey Hub streamlines deployment by preseeding system initialization settings with values the user provides before launching an instance through the Hub's cloud deployment web app.

This means when the system boots for the first time it doesn't need to interact with the user through text dialogs.

Preseeding is well documented and may be used by other hosting providers or private clouds in a similar way to streamline deployment.

Inithooks package design goals

The inithooks package executes system initialization scripts which:

• Regenerate secret keys (e.g., SSH, default SSL certificate): This isn't just a good idea, it's necessary to avoid man in the middle attacks.
• Set passwords (e.g., root, database, application): necessary to avoid the risk of hardwired default passwords
• Configure basic application settings (e.g., domain, admin email): especially useful when configuring the application would require hunting down the format of a configuration file.

Also, Inithooks provides a preseeding mechanism designed to make it easy to integrate TurnKey with custom control panels provided by various virtualization solutions and cloud hosting providers.

How it works

Inithooks itself is as generic and barebones as possible, leaving the bulk of functionality up to the appliance specific "hook" scripts themselves,

These scripts are located in two sub-directories under /usr/lib/inithooks - everyboot.d and firstboot.d.

They are executed in alphanumeric ordering. This means a script named 1-foo would be executed before 2-bar, which would itself be executed before 3-foobar. That's why scripts in these directories have funny numbers at the beginning.

The inithooks top-level init script is executed early on in system initialization, at runlevel 2 15. This enables configuration of the system prior to most services starting. This should be taken into consideration when developing hook scripts.

Setting the root password in a headless deployment

On headless deployments the user needs to login as root to complete the appliance initialization process, but how do you login as root?

Not a problem if you're using OpenNode or ProxMox - those systems prompt you to choose a root password before deploying a TurnKey image.

On OpenStack you can log in as root with your configured SSH keypair or retrieve the random root password from the "system log".

Other virtualization / private cloud solutions should be able to use their existing deployment scripts to set the root password, just like they already do with Debian and Ubuntu.

Another more advanced option is to "preseed" the /etc/inithooks.conf file in the apliance's filesystem before booting it for the first time. This lets you leverage inithooks to pre-configure not just the root password but also the database and application passwords, admin email, domain name, etc.

However note that using preseeding deactivates the "initilization fence". If you're using preseeding TurnKey assumes you've already interacted with the user some other way (e.g., web control panel) to get the preseeded configuration values.

Preseeding

By default, when an appliance is run for the first time, the firstboot scripts will prompt the user interactively, through the virtual console, to choose various passwords and basic application configuration settings.

It is possible to bypass this interactive configuration process by creating /etc/inithooks.conf in the appliance filesystem and writing inithooks configuration variables into it before the first system boot. For example:

cat>/etc/inithooks.conf<<EOF
export ROOT_PASS=supersecretrootpass
export DB_PASS=supersecretmysqlpass
export APP_EMAIL=admin@example.com
export APP_PASS=webappadminpassword
export SEC_ALERTS=admin@example.com
export SEC_UPDATES=FORCE
export HUB_APIKEY=SKIP
EOF

Don't worry about leaving sensitive passwords in there: after the first boot, inithooks blanks /etc/inithooks.conf out so important passwords aren't accidentally left in the clear.

This preseeding mechanism makes it relatively easy to integrate TurnKey with custom control panels, virtualization solutions, etc.

How exactly you create /etc/inithooks.conf is up to you and the capabilities of the virtualization platform you are using. For example, many virtualization platforms provide a facility through which you can run scripts or add files to the filesystem before the first boot.

List of initialization hooks and preseeding configuration parameters

Below is a list of interactive firstboot hooks. All interactive hooks have preseeding options to support cloud deployment, hosting and ISV integration.

Note that almost all appliances have their own application specific secret-regeneration hooks.

Common to all appliances:

30rootpass              ROOT_PASS
50auto-apt-archive      AUTO_APT_ARCHIVE        [ SKIP ]
80tklbam                HUB_APIKEY              [ SKIP ]
85secalerts             SEC_ALERTS              [ SKIP ]
92etckeeper             ETCKEEPER_COMMIT        [ SKIP ]
95secupdates            SEC_UPDATES             [ SKIP | FORCE ]

Specific to headless builds:

29preseed INITFENCE [ SKIP ]

Appliance specific:

35mysqlpass                    DB_PASS
35pgsqlpass                    DB_PASS

40ansible                      APP_PASS
40couchdb                      APP_PASS
40espocrm                      APP_PASS
40etherpad                     APP_PASS
40githttp                      APP_PASS
40icesecretset                 APP_PASS
40jenkins                      APP_PASS
40mediawiki                    APP_PASS
40mibew                        APP_PASS
40mongodb                      APP_PASS
40moodle                       APP_PASS
40mumblesupw                   APP_PASS
40observium                    APP_PASS
40odoo                         APP_PASS
40openvas                      APP_PASS
40orangehrm                    APP_PASS
40otrs                         APP_PASS
40phpmumbleadmin               APP_PASS
40plone                        APP_PASS
40sugarcrm                     APP_PASS
40suitecrm                     APP_PASS
40torrentserver                APP_PASS
40trac                         APP_PASS
40typo3                        APP_PASS
40zoneminder                   APP_PASS
40nextcloud                    APP_PASS, APP_DOMAIN
40openldap                     APP_PASS, APP_DOMAIN
40owncloud                     APP_PASS, APP_DOMAIN
40zurmo                        APP_PASS, APP_DOMAIN
40domain-controller            APP_PASS, APP_DOMAIN [, APP_REALM]
40b2evolution                  APP_PASS, APP_EMAIL
40collabtive                   APP_PASS, APP_EMAIL
40concrete5                    APP_PASS, APP_EMAIL
40django                       APP_PASS, APP_EMAIL
40dokuwiki                     APP_PASS, APP_EMAIL
40drupal7                      APP_PASS, APP_EMAIL
40e107                         APP_PASS, APP_EMAIL
40ezplatform                   APP_PASS, APP_EMAIL
40gallery                      APP_PASS, APP_EMAIL
40joomla                       APP_PASS, APP_EMAIL
40kliqqi                       APP_PASS, APP_EMAIL
40limesurvey                   APP_PASS, APP_EMAIL
40mahara                       APP_PASS, APP_EMAIL
40mambo                        APP_PASS, APP_EMAIL
40mantis                       APP_PASS, APP_EMAIL
40mattermost                   APP_PASS, APP_EMAIL
40mayan                        APP_PASS, APP_EMAIL
40moinmoin                     APP_PASS, APP_EMAIL
40omeka                        APP_PASS, APP_EMAIL
40oscommerce                   APP_PASS, APP_EMAIL
40phpbb                        APP_PASS, APP_EMAIL
40processmaker                 APP_PASS, APP_EMAIL
40redmine                      APP_PASS, APP_EMAIL
40roundup                      APP_PASS, APP_EMAIL
40silverstripe                 APP_PASS, APP_EMAIL
40simpleinvoices               APP_PASS, APP_EMAIL
40sitracker                    APP_PASS, APP_EMAIL
40twiki                        APP_PASS, APP_EMAIL
40ushahidi                     APP_PASS, APP_EMAIL
40vanilla                      APP_PASS, APP_EMAIL
40vtiger                       APP_PASS, APP_EMAIL
40wordpress                    APP_PASS, APP_EMAIL
40xoops                        APP_PASS, APP_EMAIL
40canvas                       APP_PASS, APP_EMAIL, APP_DOMAIN
40drupal8                      APP_PASS, APP_EMAIL, APP_DOMAIN
40elgg                         APP_PASS, APP_EMAIL, APP_DOMAIN
40gitlab                       APP_PASS, APP_EMAIL, APP_DOMAIN
40gnusocial                    APP_PASS, APP_EMAIL, APP_DOMAIN
40icescrum                     APP_PASS, APP_EMAIL, APP_DOMAIN
40phplist                      APP_PASS, APP_EMAIL, APP_DOMAIN
40piwik                        APP_PASS, APP_EMAIL, APP_DOMAIN
40prestashop                   APP_PASS, APP_EMAIL, APP_DOMAIN
40punbb                        APP_PASS, APP_EMAIL, APP_DOMAIN
40simplemachines               APP_PASS, APP_EMAIL, APP_DOMAIN
40zencart                      APP_PASS, APP_EMAIL, APP_DOMAIN
40magento                      APP_PASS, APP_EMAIL, APP_DOMAIN [, APP_PRIVKEY, APP_PUBKEY]
40bugzilla                     APP_PASS, APP_EMAIL [, APP_OUTMAIL]
40foodsoft                     APP_PASS, APP_EMAIL [, APP_VARIANT]
40ghost                        APP_PASS, APP_EMAIL, APP_DOMAIN [, APP_UNAME]

If not preseeded, the user will be asked interactively. The SKIP and FORCE options should be self explanatory. Note that secupdates is automatically skipped when in live demo mode.

Development notes

So you're creating a new appliance and want to add initialization hooks. Awesome! Here are some examples to get you going.

/usr/lib/inithooks/firstboot.d/20regen-joomla-secrets

#!/bin/bash -e
# regenerate joomla secret key and mysql password

. /etc/default/inithooks

updateconf() {
    CONF=/var/www/joomla/configuration.php
    sed -i "s/var $1 = \(.*\)/var $1 = '$2';/" $CONF
}

updateconf '\$secret' $(mcookie)$(mcookie)

PASSWORD=$(mcookie)
updateconf '\$password' $PASSWORD

$INITHOOKS_PATH/bin/mysqlconf.py --user=joomla --pass="$PASSWORD"

/usr/lib/inithooks/firstboot.d/30rootpass

#!/bin/bash -e
# set root password

. /etc/default/inithooks

[ -e $INITHOOKS_CONF ] && . $INITHOOKS_CONF
$INITHOOKS_PATH/bin/setpasspass.py root --pass="$ROOTPASS"

/usr/lib/inithooks/bin/setpass.py

#!/usr/bin/python
# Copyright (c) 2010 Alon Swartz <alon@turnkeylinux.org>
"""Set account password

Arguments:
    username      username of account to set password for

Options:
    -p --pass=    if not provided, will ask interactively
"""

import sys
import getopt
import subprocess
from subprocess import PIPE

from dialog_wrapper import Dialog

def fatal(s):
    print >> sys.stderr, "Error:", s
    sys.exit(1)

def usage(e=None):
    if e:
        print >> sys.stderr, "Error:", e
    print >> sys.stderr, "Syntax: %s <username> [options]" % sys.argv[0]
    print >> sys.stderr, __doc__
    sys.exit(1)

def main():
    try:
        opts, args = getopt.gnu_getopt(sys.argv[1:], "hp:", ['help', 'pass='])
    except getopt.GetoptError, e:
        usage(e)

    if len(args) != 1:
        usage()

    username = args[0]
    password = ""
    for opt, val in opts:
        if opt in ('-h', '--help'):
            usage()
        elif opt in ('-p', '--pass'):
            password = val

    if not password:
        d = Dialog('TurnKey GNU/Linux - First boot configuration')
        password = d.get_password(
            "%s Password" % username.capitalize(),
            "Please enter new password for the %s account." % username)

    command = ["chpasswd"]
    input = ":".join([username, password])

    p = subprocess.Popen(command, stdin=PIPE, shell=False)
    p.stdin.write(input)
    p.stdin.close()
    err = p.wait()
    if err:
        fatal(err)

if __name__ == "__main__":
    main()