GITANO-SETUP(1)

NAME
gitano-setup - set up a Gitano instance

SYNOPSIS
gitano-setup [-h] [--help] [--usage] [ANSWER-FILE...]

DESCRIPTION
gitano-setup creates the basic repository setup for a Gitano instance. Gitano is a git repository management system. It provides repository creation, user administration, and access control.

gitano-setup is an interactive tool where if it has any questions for you, it will visit each answers file in turn until it finds the answer. This means that for automation purposes you can specify multiple answers files with the earlier ones overriding the later ones.

In summary, the behaviour is as follows:

The repository root is created if it does not exist, and a gitano-admin.git repository is created within it. Said repository is populated with the example administration repository rules and an admin user and group. Finally the .ssh/authorized_keys file for the Gitano instance is populated with the keys to allow further configuration and use of the repositories.

  Answer files
Answer files contain key value pairs which are used to answer the questions which gitano-setup would otherwise prompt for. If the setting setup.batch is set, then gitano-setup will operate in batch mode, rather than interactively. The format is as follows:

    key.name "value"

Valid keys and the meaning of their values are:

setup.batch
    Operate in batch mode if set at all.

paths.home
    Home directory for the Gitano management user. This defaults to the HOME environment variable.

paths.ssh
    The .ssh directory for the Gitano instance. This defaults to the value of paths.home with /.ssh appended.

paths.bypasskey
    The path to a public SSH key to be used for the gitano-bypass user who will be able to do anything with access control, rules, hooks, etc. all ignored. Normally you would set this to the path to the public key held inside the paths.ssh location since only someone with access to the Gitano instance ought to have bypass capability by default. The default value for this is the value of the paths.ssh variable with id_rsa.pub or id_ecdsa.pub appended, whichever is found first (if either).

paths.pubkey
    The path to a public SSH key to be used for the newly created user with gitano-admin rights in the new Gitano instance. This defaults to the value of the paths.home variable plus admin.pub if present. Normally you would set this to the path to your public key so that you will have administration rights upon creation of the instance.

paths.repos
    The path to the repository store for the new Gitano instance. This defaults to the value of paths.home with /repos appended to it.

admin.username
    The username for the administrator of the new Gitano instance. This defaults to admin and is only relevant for rulesets inside Gitano.

admin.realname
    The real name for the administrator of the new Gitano instance. This defaults to Administrator and is only relevant inside the Gitano instance as it will be used to indicate the name of the committer of administration changes.

admin.email
    The email address of the administrator of the new Gitano instance. This defaults to admin@administrator.local and is only relevant inside the Gitano instance as it will be used to indicate the email address of the comitter of administration changes.

site.name
    The site name used in greetings and messages from Gitano. This defaults to a random Gitano instance and should always start with a lowercase letter since it will be used in sentences such as Welcome to a random Gitano instance or those with similar forms.

log.prefix
    The log prefix for the Gitano instance. This defaults to gitano and is used in messages from Gitano. Lines generated by Gitano will be prefixed with the log prefix in square brackets. For example, if log.prefix is set to 'example' then:

    [example] CRIT: Repository creation is not permitted.
    [example] FATAL: Ruleset denied action.  Sorry.

OPTIONS

-h, --help, --usage
    Print out a usage summary for the program.

BASIC USAGE

To set up a new Gitano instance:

Create the new user.
    $ sudo useradd -m git
Put the ssh key you want to use for the administrator somewhere that gitano-setup will be able to reach.
    $ sudo cp ~/.ssh/id_rsa.pub ~git/admin.pub
Run the rest of the commands as the git user.
    $ sudo -u git -i
Generate an ssh key for the bypass user of gitano. This is conventionally the same as the git unix user.
    $ ssh-keygen -t rsa
    Generating public/private rsa key pair.
    Enter file in which to save the key (/home/git/.ssh/id_rsa):
    Created directory '/home/git/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/git/.ssh/id_rsa.
    Your public key has been saved in /home/git/.ssh/id_rsa.pub.
    The key fingerprint is:
    [output elided]

Run gitano-setup and for most of the options just press enter to use the default except where bold alternative input is provided.
    $ gitano-setup
    [gitano-setup] Welcome to the Gitano setup process
    [gitano-setup] Performing system checks
    [gitano-setup] ... Checking supple sandboxing
    [gitano-setup] System checks out
    [gitano-setup] Step 1: Determine everything
    Home directory for new Gitano user [/home/git]:
    SSH directory for new Gitano user [/home/git/.ssh]:
    Public key file for bypass user [/home/git/.ssh/id_rsa.pub]:
    Public key file for admin user [/home/git/admin.pub]:
    Repository path for new Gitano instance [/home/git/repos]:
    User name for admin user [admin]:
    Real name for admin user [Administrator]:
    Email address for admin user [admin@administrator.local]: admin@example.com
    Key name for administrator [default]:
    Site name [a random Gitano instance]: Gitano for example.com
    Site log prefix [gitano]: example.com
    Store passwords with htpasswd? (needed for http authentication) [no]:
    Path to skeleton gitano-admin content [/usr/share/gitano/skel/gitano-admin]:
    [gitano-setup] Step 2: Gather required content
    [gitano-setup] Step 3: Write out paths and gitano-admin.git
    [gitano-setup] <gitano-admin> Set project.description to <Instance administration repository>
    [gitano-setup] <gitano-admin> Set project.owner to <admin>
    [gitano-setup] SSH authorised key file updated

At this point the ~git/admin.pub public key can be cleaned up from the git user's home directory.
    $ rm -f ~git/admin.pub

ssh will complain about having a new key. ssh-keyscan can be used to explicitly accept those hosts.
    $ ssh-keyscan localhost >>~git/.ssh/known_hosts
    [output elided]
We can run commands as the git user by looping back through ssh though Gitano will complain because the bypass key is only meant to be used in emergencies.
    $ ssh git@localhost whoami
    [example.com] **** ALERT **** ALERT ****  PAY CAREFUL ATTENTION  **** ALERT **** ALERT ****
    [example.com] **** You are acting as the bypass user.  Rules and hooks WILL NOT APPLY  ****
    [example.com] **** ALERT **** ALERT **** DO NOT DO THIS NORMALLY **** ALERT **** ALERT ****
    [example.com] **** DANGER **** SOMETHING RISKY HAPPENING **** DANGER ****
    [example.com] **** An ACL check was bypassed thanks to gitano-bypass ****
    [example.com] **** DANGER **** ACL BYPASS IS VERY RISKY  **** DANGER ****
        User name: gitano-bypass
        Real name: Special site-wide rule/hook bypass user
    Email address: admin@example.com
          SSH key: initial => git@surtur-linux [*]
If things break we will need to be able to access the gitano-admin repository directly, which can be accessed by cloning the repository using the bypass key.
    $ git clone ssh://git@localhost/gitano-admin.git
    Cloning into 'gitano-admin'...
    [example.com] **** ALERT **** ALERT ****  PAY CAREFUL ATTENTION  **** ALERT **** ALERT ****
    [example.com] **** You are acting as the bypass user.  Rules and hooks WILL NOT APPLY  ****
    [example.com] **** ALERT **** ALERT **** DO NOT DO THIS NORMALLY **** ALERT **** ALERT ****
    [example.com] **** DANGER **** SOMETHING RISKY HAPPENING **** DANGER ****
    [example.com] **** An ACL check was bypassed thanks to gitano-bypass ****
    [example.com] **** DANGER **** ACL BYPASS IS VERY RISKY  **** DANGER ****
    remote: Counting objects: 24, done.
    remote: Compressing objects: 100% (23/23), done.
    remote: Total 24 (delta 0), reused 0 (delta 0)
    Receiving objects: 100% (24/24), 5.06 KiB | 0 bytes/s, done.
    Checking connectivity... done.

We can do the same with our normal unix user without getting the warning.
    $ ^D
    $ ssh-keyscan localhost >>~/.ssh/known_hosts
    [output elided]
    $ ssh git@localhost whoami
        User name: admin
        Real name: Administrator
    Email address: admin@example.com
          SSH key: default => admin@example.com [*]
        In groups: gitano-admin: Gitano Instance Administrators
    $ ssh git@localhost ls
    RW  gitano-admin
    $ git clone ssh://git@localhost/gitano-admin.git
    Cloning into 'gitano-admin'...
    remote: Counting objects: 24, done.
    remote: Compressing objects: 100% (23/23), done.
    remote: Total 24 (delta 0), reused 0 (delta 0)
    Receiving objects: 100% (24/24), 5.06 KiB | 0 bytes/s, done.
    Checking connectivity... done.

This has set up Gitano in a newly created git user on the machine the gitano administrator is logged into, using the ssh key of their user account. See the Gitano wiki for other ways to set Gitano up.

This has tested basic command operation with whoami and repository access by cloning the gitano-admin repository. For more information consult the online help with the help command, the Gitano Administrator's manual or the Gitano wiki.