DOKK / manpages / debian 10 / gitano / gitano-setup.1.en
GITANO-SETUP(1) General Commands Manual GITANO-SETUP(1)

gitano-setup - set up a Gitano instance

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

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 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:



  

  
Operate in batch mode if set at all.

  

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

  

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

  

  
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).

  

  
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.

  

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

  

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

  

  
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.

  

  
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.

  

  
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.

  

  
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.















  

  
Print out a usage summary for the program.










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.