Provided by: gitano_1.1-1_all 
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.
GITANO-SETUP(1)