Provided by: gitano_1.2-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)