Tech Notes: Git server and Jira on Debian

Nothing special, just yet another "I've done it this way" installation log.
But hey, did you know that the word "blog" comes from "web log"? So here it is :D.

Base OS

Start from a minimal Debian installation.

Git server

Start from this howto.

It's not 100%, because some config formats have changed since then, so here are the differences:

Repo name

Where it says repo1.git, choose your own repo name. Choose a descriptive one and save the constant need for explanation.

Git config files

It uses a separate /etc/gitdata, I found /opt/allgit more convenient:

* It's also not publicly accessible
* All related files are at the same place

So I put gitusers.passwd and the certificates also here.

The SSL certificate

When creating the cert as the howto tells to, openssl will ask about the identity for whom to create the cert. For the CN (Common Name) enter the public hostname of your server, the rest is up to you, technically it doesn't matter.

Besides, the command in the blog indeed generates a self-signed cert, but also marks it as a CA cert (because that it is).

This is fine, but Apache will dump warnings in the log:
AH01906: <your public hostname>:443:0 server certificate is a CA certificate (BasicConstraints: CA == TRUE !?)

Normally you would have one cert and its private key for your server, and one cert (without its priv key) from the CA authority that testifies for your server cert.

Here you have one certificate and the private key that belongs to it, that's all, and this certificate plays
both roles: it acts as a server cert, and also a CA cert that has signed your server cert ('self-signed', it is).

Apache modules

The actual command is a2enmod ssl cgi alias env.

A public http space

Your git repos will be accessible as https://<your public hostname>/allgit/repos/some_repo.git, that's fine.

But you may need a generic https://<your public hostname>/<whatever> space, at least for not displaying the default Apache placeholder.

mkdir -p /opt/allgit/public

Whatever you put in this folder, it'll be accessible like the generic link above.

About the Certificate Verification Error

A self-signed cert tells the client that you are who you say you are, just because you say so.

If the client accepts you as trustworthy, then believes what you say, that you are who you say you are :). If he accepts you as trustworthy, that is, otherwise your browser will throw those 'security alert' windows at you, and the commandline clients (like git) will just exit with an appropriate error.

So, you must add your CA certificate to the 'trusted' group at your client.

Disabling the cert checks for git

The howto tells you can, and it indeed would work, but believe me, it's a bad idea.

Anyway, here's the command: git config --global http.sslVerify false

However, you'd rather add the cert to the client's trusted group, it's not that complex.

Adding your CA certificate to the client's trusted group

The client has a folder in which it contains all the CA certificates it considers trusted, you shall

put your CA cert (in this case, the cert), but the filename must be a special one instead of mygit_ssl.crt.

Why (skip this if not interested)

There is a technical reason for it: When the client receives a cert from a server, it wants to check whether it was signed by a trusted CA, so theoretically it should look up all the trusted CA certs and check whether it has signed the server cert or not. This is time-consuming, because there can be quite a many of trusted CA certs.

On the other hand, if the filename of the required CA cert could be identified by some means, then there would be no need to check all the CA certs, it would be enough to read just the required one.

This is achieved by a checksum-like trick: for all CA cert a checksum is calculated from the name of the authority they represent, and this checksum gives the beginning part of the filename.

(NOTE: I say checksum and name of the authority, but in fact there's a more complex hash algorithm used and it's applied to the full Distinguished Name of the issuer, not to the human-readable one. Anyway, the principle is the same.)

So when the client sees a server cert, it just reads the name of the authority that has (allegedly) signed that server cert, calculates that checksum for it, and if there indeed is a trusted CA cert representing that authority, its filename will begin with that checksum, so the client must check only a few trusted CA cert files instead of all of them.

Why few and not just the one? This is a checksum, necessarily shorter than the information from which it is calculated, so theoretically there can be more than one CA authorities whose name gives the same checksum.

Therefore the actual name of the file is like <checksum>.<idx> where this idx is just an incremental number, starting from 0, so if there are two CAs whose names give the same checksum 12345678, then their filenames will be 12345678.0 and 12345678.1 respectively.

How to get this filename

cp /opt/allgit/mygit_ssl.crt /opt/allgit/public/$(openssl x509 -noout -hash -in /opt/allgit/mygit_ssl.crt).0

ls -l /opt/allgit/public/

Now we've copied our certificate to the publicly available space (it may be published, just the private key is to be kept secret), with an appropriate name.

On the client you may download it with a browser like https://<your public hostname>/12345678.0

What to do on the client side

Create a folder if it doesn't yet exist: mkdir -p /etc/ssl/certs, download the cert file into it.

Make it world readable but writable only for the owner:
chmod 644 /etc/ssl/certs/12345678.0

make it owned by root:
chown root:root /etc/ssl/certs/12345678.0

And finally git to use it system-wide:
git config --system http.sslCAPath /etc/ssh/certs

This way you configured it for all users on the client machine.

If you are just one user, and don't have root access, then create the folder as ~/certs and

tell git to set only your global config (instead of the system-wide one):
git config --global http.sslCAPath ~/certs

Jira

A few words in advance.

Jira will set up itself as an independent web server that listens on http://localhost:8080/whatever, that is, separate port, no encryption, and everything on this 'host:port' is assumed to belong to Jira.

But our server is not dedicated just to it, we'd like to access it at https://<your public hostname>/jira/whatever, that is, standard https port, SSL encryption, and only the part after /jira belongs to Jira.

This is possible, but we need some configurations to change a bit.

The second issue is that Jira and the IPv6 support of Debian are not fully compatible, so we'll need to disable IPv6.

I've tried the mentioned _JAVA_OPTIONS setting, it didn't work.

The symptoms were: after installation Jira starts fine and listens on 8080, but if I stop and restart it

as a service (or manually, doesn't matter), it starts, but doesn't listen on 8080.

So, roll up your sleeve, take a sip of your coffee, and let's begin :).

Disable IPv6

Edit /etc/sysctl.conf as described here.

In addition, edit /etc/ssh/sshd_config and change AddressFamily any to AddressFamily inet (uncomment it as well, if it's still commented out).

Then reboot the server - sorry, no way to do it online.

Set up Apache to act as Reverse Proxy

Reverse proxying means that technically the Apache will receive the incoming https://.../jira/whatever requests, but instead of processing them by itself, it'll pass them on to Jira, with rewriting the URLs as needed.

There is a nice description of the concept here, but as usual, it's not 100% applicable, things have changed a bit since then.

Some more apache modules

a2enmod proxy proxy_http proxy_connect

Edit /etc/apache2/mods-enabled/proxy.conf and uncomment the Proxy block.

Site config

Edit /etc/apache2/sites-available/<your public hostname>.conf again:

...

# ==== for Jira

ProxyRequests On

ProxyVia On

Options Indexes FollowSymLinks

AllowOverride None

Require all granted

ProxyPass "http://127.0.0.1:8080/jira"

ProxyPassReverse "http://127.0.0.1:8080/jira"

</Location>

</VirtualHost>

# vim: syntax=apache ts=4 sw=4 sts=4 sr noet

This tells Apache that whenever it gets something that starts with /jira, it shall pass it on

to Jira, by rewriting that /jira to http://127.0.0.1:8080/jira (keeping whatever follows in the URL).

NOTE: By default Jira will expect http://127.0.0.1:8080/, so we must reconfigure it to use the /jira path instead of just /.

Restart Apache

Easy to forget, annoying to debug :).

systemctl restart apache2

Install Jira

Just follow the official howto. For the impatient, here is the current installer for linux/x86_64.

The default installer method is fine (no need for custom), only at the last question, whether it shall start Jira right away, should you say 'no'.

Configure Jira to use the '/jira' path

Open this howto, and see 'Step 1 Configure Tomcat', and '2 set the context path' within it.

The other sub-steps are NOT needed, they refer to a different situation, when the Jira server is completely separated from the internet, which is not the case here.

Start Jira

The moment of truth :D.

systemctl start jira

top

Wait until it settles and the load goes down (it does some initialisation before actually starts listening), then check if it managed to start up:

ps axufww | grep java

If you see a multi-line crap of a command that starts with /opt/atlassian/jira/jre//bin/java, you're halfway home.

If not, then see the logs in /opt/atlassian/jira/logs/, but they are not the most straightforward kind, prepare for heavy googling and you may as well open stackoverflow.com too.

Check if it listens for incoming connections:

netstat -4nlp | grep 8080

If you see the process above (like 1118/java), your Jira is up, so if Apache passes some requests to it, it may even work.

If you seen nothing here, regardless of the fact that the Jira process is running, you're deep in Trouble County. Check if IPv6 is indeed disabled (ifconfig shall show no inet6 addresses).

If it is, then I'm out of ideas, and I bet the logs won't help much either. Google, SO, try some magicks, some may even do the trick, provided that the rest hasn't wrecked your system to crap by the time you find the good ones... If you ran into it and found something useful, please leave a comment with the details (OS version, Jira version, the magick that killed the beast, etc.) for the rest of us!

PostgreSQL

You'll need a postgres to store the data for Jira and Confluence, and you may start with the official howto. Almost 100%, as usual.

As of Postgres config, as long as you want to access the DB only from localhost and only by users

whose unix username matches the database username (for Jira this is the case), its the default config will suffice.

Things that differ from the howto:

Version

Now it's 9.6 instead of 8.4.

Enable and start

Don't forget to enable and start the DB after installation:

systemctl enable postgresql

systemctl start postgresql

DB User

As of 9.6, the createdb command won't ask you questions, but expect the options for the role as

commandline options.

The right to create DBs is given by -d, so your command is createuser -P -d jira .

If you messed up, just dropuser jira and try again.

Choose a nice random password, it'll be needed only once, when you tell it to the Jira setup.

(My favourite password generator is the pwgen package: pwgen --no-numerals --no-capitalize 12, it dumps a screenload of more-or-less intelligible but still random passwords, pick one and use it. Far better than 'Jira!123', maybe a bit weaker than correct horse battery staple, but still meets most of the stupid password criteria...)

Jira setup

The final steps can be done via your browser.

On your client, open https://<your public hostname>/jira, you shall get a nice Jira setup page.

If you don't, check the apache logs in /var/log/apache2/<your public hostname>.log on the server, there's most probably some typo in the apache proxy setup (spaces and slashes do make a difference there!)

On the Jira setup page choose to do it for yourself, choose an external DB, set it to Postgres,

host=127.0.0.1, port=5432, db name is the db name you created, username is 'jira', password is the

nice random password you've chosen, Test DB Connection.

On the next screen set an App Title, and set the Base URL to https://<your public hostname>/jira!

That's all, you're done :D !

Tech Notes

Wednesday, June 13, 2018

Git server and Jira on Debian