Skip to content
Snippets Groups Projects
Commit 04ad3604 authored by ovari's avatar ovari Committed by Adrien Béraud
Browse files

jams/admin.md: cleanup (attempt 2) 

Follow up to patch: https://review.jami.net/c/jami-docs/+/29999

fix formatting of `code`

Change-Id: Ifa346227a35acf6736b87d725a4335e1907d0741
parent ba06c6b2
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 120 additions and 131 deletions
jams/admin.md
+ 120
− 131
View file @ 04ad3604
...@@ -4,7 +4,6 @@ By default, the [Jami Account Management Server (JAMS)](https://jami.biz/) runs ...@@ -4,7 +4,6 @@ By default, the [Jami Account Management Server (JAMS)](https://jami.biz/) runs
However, this is impractical for many reasons. However, this is impractical for many reasons.
This guide is designed to help with setting up a JAMS to run in a production environment. This guide is designed to help with setting up a JAMS to run in a production environment.
## JAMS and Nginx ## JAMS and Nginx
It is generally not recommended to expose JAMS directly to the outside world. It is generally not recommended to expose JAMS directly to the outside world.
...@@ -22,28 +21,28 @@ The IP 10.10.0.1 is random and should be seen as an example. ...@@ -22,28 +21,28 @@ The IP 10.10.0.1 is random and should be seen as an example.
Typically a new site called `jams-site.conf` would be added to the Nginx configuration. Typically a new site called `jams-site.conf` would be added to the Nginx configuration.
It would contain the following entries if an SSL certificate was placed at the Nginx level: It would contain the following entries if an SSL certificate was placed at the Nginx level:
<pre> <pre>
server { server {
listen 443 ssl; listen 443 ssl;
listen [::]:443 ssl; listen [::]:443 ssl;
ssl on; ssl on;
ssl_certificate /etc/certificates/mycertificate.pem ssl_certificate /etc/certificates/mycertificate.pem
ssl_certificate_key /etc/certificates/mycertificatekey.pem ssl_certificate_key /etc/certificates/mycertificatekey.pem
ssl_client_certificate /jams/installation/path/CA.pem; ssl_client_certificate /jams/installation/path/CA.pem;
ssl_verify_client optional; ssl_verify_client optional;
ssl_verify_depth 2; ssl_verify_depth 2;
client_max_body_size 100M; client_max_body_size 100M;
server_name jams.mycompany.com; server_name jams.mycompany.com;
location / { location / {
# Block client-supplied headers that could be used to spoof # Block client-supplied headers that could be used to spoof
if ($http_x_client_cert) { if ($http_x_client_cert) {
return 400; return 400;
} }
proxy_pass http://10.10.0.1:8080/; proxy_pass http://10.10.0.1:8080/;
proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $http_host; proxy_set_header Host $http_host;
proxy_set_header X-Client-Cert $ssl_client_escaped_cert; proxy_set_header X-Client-Cert $ssl_client_escaped_cert;
} }
}</pre> }</pre>
This is the preferred setup method by most admins, as local traffic is usually run unencrypted since it is usually either an inter-VM connection, a VLAN, or another dedicated link. This is the preferred setup method by most admins, as local traffic is usually run unencrypted since it is usually either an inter-VM connection, a VLAN, or another dedicated link.
...@@ -51,58 +50,52 @@ This is the preferred setup method by most admins, as local traffic is usually r ...@@ -51,58 +50,52 @@ This is the preferred setup method by most admins, as local traffic is usually r
Since the CA is generated during the JAMS initial configuration, Nginx needs to be restarted once the initial setup is completed. Since the CA is generated during the JAMS initial configuration, Nginx needs to be restarted once the initial setup is completed.
``` ```
## Troubleshooting and resetting ## Troubleshooting and resetting
If a restart from 0 (i.e., reset everything and drop existing data) is required, delete the following files in the distribution folder (`<project-root-folder>/jams`): If a restart from 0 (i.e., reset everything and drop existing data) is required, delete the following files in the distribution folder (`<project-root-folder>/jams`):
<pre> <pre>
The internal JAMS folder: &lt;project-root-folder>/jams/jams The internal JAMS folder: &lt;project-root-folder>/jams/jams
derby.log derby.log
oauth.key oauth.key
oauth.pub oauth.pub
config.json config.json
</pre> </pre>
This will reset the server to its original state, and the configuration wizard is able to be run again. This will reset the server to its original state, and the configuration wizard is able to be run again.
Before performing this operation, please ensure that the server is shut down. Before performing this operation, please ensure that the server is shut down.
## Running JAMS as a GNU/Linux Service ## Running JAMS as a GNU/Linux Service
Running JAMS as a GNU/Linux Service is fairly straightforward with systemd—simply create a service unit file with the following structure: Running JAMS as a GNU/Linux Service is fairly straightforward with systemd—simply create a service unit file with the following structure:
<pre> <pre>
<b>[Unit]</b> <b>[Unit]</b>
Description=JAMS Server Description=JAMS Server
<b>[Service]</b> <b>[Service]</b>
Type=simple Type=simple
WorkingDirectory=[DIRECTORY WHERE JAMS WAS UNZIPPED] WorkingDirectory=[DIRECTORY WHERE JAMS WAS UNZIPPED]
ExecStart=/usr/bin/java -jar [DIRECTORY WHERE JAMS WAS UNZIPPED]/jams-launcher.jar PORT SSL_CERTIFICATE SSL_CERTIFICATE_KEY ExecStart=/usr/bin/java -jar [DIRECTORY WHERE JAMS WAS UNZIPPED]/jams-launcher.jar PORT SSL_CERTIFICATE SSL_CERTIFICATE_KEY
<b>[Install]</b> <b>[Install]</b>
WantedBy=multi-user.target WantedBy=multi-user.target
</pre> </pre>
The parameters **PORT**, **SSL_CERTIFICATE** and **SSL_CERTIFICATE_KEY** are optional (however, **PORT** can be used alone, whereas the **SSL_CERTIFICATE** comes in a pair with **SSL_CERTIFICATE_KEY**). The parameters **PORT**, **SSL_CERTIFICATE** and **SSL_CERTIFICATE_KEY** are optional (however, **PORT** can be used alone, whereas the **SSL_CERTIFICATE** comes in a pair with **SSL_CERTIFICATE_KEY**).
## Running JAMS as a Windows Service ## Running JAMS as a Windows Service
### A. Download and install JAMS ### A. Download and install JAMS
1. Visit <https://jami.biz/> and download JAMS. 1. Visit <https://jami.biz/> and download JAMS.
2. Extract JAMS to C:\jams 2. Extract JAMS to C:\jams
### B. Download and install Java Development Kit (JDK) ### B. Download and install Java Development Kit (JDK)
1. Download JDK 11 from <https://www.oracle.com/java/technologies/javase-jdk11-downloads.html> (choose the corresponding VM architecture). 1. Download JDK 11 from <https://www.oracle.com/java/technologies/javase-jdk11-downloads.html> (choose the corresponding VM architecture).
2. Install it using the installation wizard. 2. Install it using the installation wizard.
### C. Download OpenSSL to generate a key and a certificate ### C. Download OpenSSL to generate a key and a certificate
1. Download the OpenSSL Binary Distributions for Microsoft Windows from <https://kb.firedaemon.com/support/solutions/articles/4000121705>. 1. Download the OpenSSL Binary Distributions for Microsoft Windows from <https://kb.firedaemon.com/support/solutions/articles/4000121705>.
...@@ -116,87 +109,85 @@ The parameters **PORT**, **SSL_CERTIFICATE** and **SSL_CERTIFICATE_KEY** are opt ...@@ -116,87 +109,85 @@ The parameters **PORT**, **SSL_CERTIFICATE** and **SSL_CERTIFICATE_KEY** are opt
5. Copy and paste the default configuration below from <http://www.flatmtn.com/article/setting-openssl-create-certificates.html>. 5. Copy and paste the default configuration below from <http://www.flatmtn.com/article/setting-openssl-create-certificates.html>.
<pre> <pre>
<i># <i>#
# OpenSSL configuration file. # OpenSSL configuration file.
# #
# Establish working directory. # Establish working directory.
</i> </i>
dir = . dir = .
<b>[ca]</b> <b>[ca]</b>
default_ca = CA_default default_ca = CA_default
<b>[CA_default]</b> <b>[CA_default]</b>
serial = $dir/serial serial = $dir/serial
database = $dir/certindex.txt database = $dir/certindex.txt
new_certs_dir = $dir/certs new_certs_dir = $dir/certs
certificate = $dir/cacert.pem certificate = $dir/cacert.pem
private_key = $dir/private/cakey.pem private_key = $dir/private/cakey.pem
default_days = 365 default_days = 365
default_md = md5 default_md = md5
preserve = no preserve = no
email_in_dn = no email_in_dn = no
nameopt = default_ca nameopt = default_ca
certopt = default_ca certopt = default_ca
policy = policy_match policy = policy_match
<b>[policy_match]</b> <b>[policy_match]</b>
countryName = match countryName = match
stateOrProvinceName = match stateOrProvinceName = match
organizationName = match organizationName = match
organizationalUnitName = optional organizationalUnitName = optional
commonName = supplied commonName = supplied
emailAddress = optional emailAddress = optional
<b>[req]</b> <b>[req]</b>
default_bits = 1024 <i># Size of keys</i> default_bits = 1024 <i># Size of keys</i>
default_keyfile = key.pem <i># Name of generated keys</i> default_keyfile = key.pem <i># Name of generated keys</i>
default_md = md5 <i># Message digest algorithm</i> default_md = md5 <i># Message digest algorithm</i>
string_mask = nombstr <i># Permitted characters</i> string_mask = nombstr <i># Permitted characters</i>
distinguished_name = req_distinguished_name distinguished_name = req_distinguished_name
req_extensions = v3_req req_extensions = v3_req
<b>[req_distinguished_name]</b> <b>[req_distinguished_name]</b><i>
<i># Variable name Prompt string # Variable name Prompt string
#-------------------------- -----------------------------------------------</i> #-------------------------- -----------------------------------------------</i>
0.organizationName = Organization Name (company) 0.organizationName = Organization Name (company)
organizationalUnitName = Organizational Unit Name (department, division) organizationalUnitName = Organizational Unit Name (department, division)
emailAddress = Email Address emailAddress = Email Address
emailAddress_max = 40 emailAddress_max = 40
localityName = Locality Name (city, district) localityName = Locality Name (city, district)
stateOrProvinceName = State or Province Name (full name) stateOrProvinceName = State or Province Name (full name)
countryName = Country Name (2 letter code) countryName = Country Name (2 letter code)
countryName_min = 2 countryName_min = 2
countryName_max = 2 countryName_max = 2
commonName = Common Name (hostname, IP, or username) commonName = Common Name (hostname, IP, or username)
commonName_max = 64 commonName_max = 64
<i># Default values for the above, for consistency and less typing. <i># Default values for the above, for consistency and less typing.
# Variable name Value # Variable name Value
#-------------------------- -----------------------------------------------</i> #-------------------------- -----------------------------------------------</i>
0.organizationName_default = My Company 0.organizationName_default = My Company
localityName_default = My Town localityName_default = My Town
stateOrProvinceName_default = State or Province stateOrProvinceName_default = State or Province
countryName_default = US countryName_default = US
<b>[v3_ca]</b> <b>[v3_ca]</b>
basicConstraints = CA:TRUE basicConstraints = CA:TRUE
subjectKeyIdentifier = hash subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer:always authorityKeyIdentifier = keyid:always,issuer:always
<b>[v3_req]</b> <b>[v3_req]</b>
basicConstraints = CA:FALSE basicConstraints = CA:FALSE
subjectKeyIdentifier = hash subjectKeyIdentifier = hash
</pre> </pre>
### D. Add OpenSSL to System Environment Variables ### D. Add OpenSSL to System Environment Variables
Go to Edit the system environment variables → Environment Variables. Go to Edit the system environment variables → Environment Variables.
In System variables, edit **Path** and add `C:\openssl\`. In System variables, edit **Path** and add `C:\openssl\`.
### E. Configure OpenSSL ### E. Configure OpenSSL
1. Open the **Command Prompt**. 1. Open the **Command Prompt**.
...@@ -214,20 +205,20 @@ In System variables, edit **Path** and add `C:\openssl\`. ...@@ -214,20 +205,20 @@ In System variables, edit **Path** and add `C:\openssl\`.
6. Once the key and certificate are generated, type `dir`. 6. Once the key and certificate are generated, type `dir`.
The output should look like: The output should look like:
<pre> <pre>
C:\jams>dir C:\jams>dir
Volume in drive C has no label. Volume in drive C has no label.
Volume Serial Number is BC94-9EF2<br> Volume Serial Number is BC94-9EF2<br>
Directory of C:\jams<br> Directory of C:\jams<br>
2020-11-10 12:38 PM &lt;DIR> . 2020-11-10 12:38 PM &lt;DIR> .
2020-11-10 12:38 PM &lt;DIR> .. 2020-11-10 12:38 PM &lt;DIR> ..
2020-10-22 10:56 AM 5,186,016 jams-launcher.jar 2020-10-22 10:56 AM 5,186,016 jams-launcher.jar
2020-10-22 10:56 AM 33,413,882 jams-server.jar 2020-10-22 10:56 AM 33,413,882 jams-server.jar
2020-11-10 11:53 AM &lt;DIR> libs 2020-11-10 11:53 AM &lt;DIR> libs
2020-11-10 12:34 PM 1,732 server.key 2020-11-10 12:34 PM 1,732 server.key
2020-11-10 12:38 PM 1,336 server.pem 2020-11-10 12:38 PM 1,336 server.pem
2020-10-22 04:05 PM 2,047,932 userguide.pdf 2020-10-22 04:05 PM 2,047,932 userguide.pdf
5 File(s) 40,650,898 bytes 5 File(s) 40,650,898 bytes
3 Dir(s) 93,365,936,128 bytes free 3 Dir(s) 93,365,936,128 bytes free
</pre> </pre>
7. Execute the following command to start JAMS: 7. Execute the following command to start JAMS:
...@@ -237,10 +228,9 @@ In System variables, edit **Path** and add `C:\openssl\`. ...@@ -237,10 +228,9 @@ In System variables, edit **Path** and add `C:\openssl\`.
9. Type CTRL+C to close the application. 9. Type CTRL+C to close the application.
### F. Expose the localhost to the Internet ### F. Expose the localhost to the Internet
1. Click on **Windows** and search for ***Windows Defender Firewall with Advanced Security***. 1. Press the Windows key or click the Windows icon and search for ***Windows Defender Firewall with Advanced Security***.
2. Right-click **Inbound Rules** and click **New Rule…** 2. Right-click **Inbound Rules** and click **New Rule…**
...@@ -269,7 +259,6 @@ In System variables, edit **Path** and add `C:\openssl\`. ...@@ -269,7 +259,6 @@ In System variables, edit **Path** and add `C:\openssl\`.
14. The localhost is now available on the Internet. 14. The localhost is now available on the Internet.
The application can now be visited through the server domain name or IP address on port 443 or 8443. The application can now be visited through the server domain name or IP address on port 443 or 8443.
### G. Create a JAMS Windows Service (Embed Tomcat Server Windows Service) to start JAMS with the server ### G. Create a JAMS Windows Service (Embed Tomcat Server Windows Service) to start JAMS with the server
1. In order to create a JAMS Windows Service, the **NSSM (the Non-Sucking Service Manager)** can be used. 1. In order to create a JAMS Windows Service, the **NSSM (the Non-Sucking Service Manager)** can be used.
...@@ -277,27 +266,27 @@ In System variables, edit **Path** and add `C:\openssl\`. ...@@ -277,27 +266,27 @@ In System variables, edit **Path** and add `C:\openssl\`.
2. Once NSSM has successfully downloaded, open a **Command Prompt** and change the directory to: 2. Once NSSM has successfully downloaded, open a **Command Prompt** and change the directory to:
<pre> <pre>
nssm-2.24\win64 nssm-2.24\win64
</pre> </pre>
3. To install and open a graphical user interface (GUI), type: 3. To install and open a graphical user interface (GUI), type:
<pre> <pre>
nssm.exe install JAMS nssm.exe install JAMS
</pre> </pre>
4. In the **Path** field, specify the path to the Java executable, for example: 4. In the **Path** field, specify the path to the Java executable, for example:
<pre> <pre>
"C:\Program Files\Common Files\Oracle\Java\javapath\java.exe" "C:\Program Files\Common Files\Oracle\Java\javapath\java.exe"
</pre> </pre>
5. In the **Startup directory**, for the installation folder path, type: 5. In the **Startup directory**, for the installation folder path, type:
<pre> <pre>
"C:\jams" "C:\jams"
</pre> </pre>
6. In the last field, add the following arguments: 6. In the last field, add the following arguments:
<pre> <pre>
-classpath "C:\jams" -jar jams-launcher.jar PORT_NUMBER server.pem server.key -classpath "C:\jams" -jar jams-launcher.jar PORT_NUMBER server.pem server.key
</pre> </pre>
where **PORT_NUMBER** is the port number to use to serve the application, for example, ***443*** or ***8443***. where **PORT_NUMBER** is the port number to use to serve the application, for example, ***443*** or ***8443***.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment