path: root/doc/gitano-setup.1

.\" =*= License: BSD =*=
.TH GITANO-SETUP 1
.SH NAME
gitano\-setup \- set up a Gitano instance
.SH SYNOPSIS
.B gitano\-setup
.RB [ -h ]
.RB [ --help ]
.RB [ --usage ]
.RB [ ANSWER-FILE ...]
.SH DESCRIPTION
.B 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.
.PP
.B 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.
.PP
In summary, the behaviour is as follows:
.PP
The repository root is created if it does not exist, and a
.I 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
.I .ssh/authorized_keys
file for the Gitano instance is populated with the keys to allow further
configuration and use of the repositories.
.SS "Answer files"
Answer files contain key value pairs which are used to answer the questions
which
.B gitano-setup
would otherwise prompt for.  If the setting
.I setup.batch
is set, then
.B gitano-setup
will operate in batch mode, rather than interactively.  The format is as
follows:
.PP
.nf
.RS
key.name "value"
.RE
.fi
.PP
Valid keys and the
meaning of their values are:
.TP
.BR setup.batch
Operate in batch mode if set at all.
.TP
.BR paths.home
Home directory for the Gitano management user.  This defaults to the
.B HOME
environment variable.
.TP
.BR paths.ssh
The
.I .ssh
directory for the Gitano instance.  This defaults to the value of
.B paths.home
with
.I /.ssh
appended.
.TP
.BR paths.bypasskey
The path to a public SSH key to be used for the
.I 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
.I 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
.I paths.ssh
variable with
.I id_rsa.pub
or
.I id_ecdsa.pub
appended, whichever is found first (if either).
.TP
.BR paths.pubkey
The path to a public SSH key to be used for the newly created user with
.I gitano-admin
rights in the new Gitano instance.  This defaults to the value of the
.I paths.home
variable plus
.I 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.
.TP
.BR paths.repos
The path to the repository store for the new Gitano instance.  This defaults
to the value of
.I paths.home
with
.I /repos
appended to it.
.TP
.BR admin.username
The username for the administrator of the new Gitano instance.  This defaults
to
.I admin
and is only relevant for rulesets inside Gitano.
.TP
.BR admin.realname
The real name for the administrator of the new Gitano instance.  This defaults
to
.I Administrator
and is only relevant inside the Gitano instance as it will be used to indicate
the name of the committer of administration changes.
.TP
.BR admin.email
The email address of the administrator of the new Gitano instance.  This
defaults to
.I 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.
.TP
.BR site.name
The site name used in greetings and messages from Gitano.  This defaults to
.I a random Gitano instance
and should always start with a lowercase letter since it will be used in
sentences such as
.B Welcome to
.I a random Gitano instance
or those with similar forms.
.TP
.BR log.prefix
The log prefix for the Gitano instance.  This defaults to
.I 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
.I log.prefix
is set to 'example' then:
.PP
.nf
.RS
[example] CRIT: Repository creation is not permitted.
[example] FATAL: Ruleset denied action.  Sorry.
.RE
.fi
.PP
.SH OPTIONS
.TP
.BR \-h ", " \-\-help ", " \-\-usage
Print out a usage summary for the program.
.SH BASIC USAGE
.PP
To set up a new Gitano instance:
.PP
Create the new user.
.nf
.RS
.RB "$" " sudo useradd -m git"
.RE
.fi
Put the ssh key you want to use for the administrator
somewhere that
.B gitano-setup
will be able to reach.
.nf
.RS
.RB "$" " sudo cp ~/.ssh/id_rsa.pub ~git/admin.pub"
.RE
.fi
Run the rest of the commands as the
.B git
user.
.nf
.RS
.RB "$" " sudo -u git -i"
.RE
.fi
Generate an ssh key for the bypass user of gitano.
This is conventionally the same as the git unix user.
.nf
.RS
.RB "$" " 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]
.RE
.fi
.PP
Run
.B gitano-setup
and for most of the options just press enter to use the default
except where bold alternative input is provided.
.nf
.RS
.RB "$" " 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]: 
.RB "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
.RB "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
.RE
.fi
.PP
At this point the
.I ~git/admin.pub
public key can be cleaned up from the git user's home directory.
.nf
.RS
.RB "$" " rm -f ~git/admin.pub"
.RE
.fi
.PP
.B ssh
will complain about having a new key.
.B ssh-keyscan
can be used to explicitly accept those hosts.
.nf
.RS
.RB "$" " ssh-keyscan localhost >>~git/.ssh/known_hosts"
[output elided]
.RE
.fi
We can run commands as the git user by looping back through
.B ssh
though Gitano will complain
because the bypass key is only meant to be used in emergencies.
.nf
.RS
.RB "$" " 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 [*]
.RE
.fi
If things break we will need to be able to access the
.I gitano-admin
repository directly,
which can be accessed by cloning the repository using the bypass key.
.nf
.RS
.RB "$" " 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.
.RE
.fi
.PP
We can do the same with our normal unix user without getting the warning.
.nf
.RS
.RB "$" " ^D"
.RB "$" " ssh-keyscan localhost >>~/.ssh/known_hosts"
[output elided]
.RB "$" " 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
.RB "$" " ssh git@localhost ls"
RW  gitano-admin
.RB "$" " 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.
.RE
.fi
.PP
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.
.PP
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.