ULYSSIS documentation - User contributions [en]

Getting SSL/TLS

2022-04-30T07:25:23Z

Wtas: Typo fix in intro

ULYSSIS does not sell or offer any other SSL certificates than our self-signed certificate. We will however guide requests and install a certificate from the KU Leuven if you are eligible for one, and we will also install certificates you have bought or obtained elsewhere.

==Requesting SSL from the KU Leuven==

The KU Leuven partners with other universities through TERENA/Géant to arrange certificates for its services, organisations and academic structures. We have permission to request free SSL/TLS certificates for student unions (kringen) recognized by LOKO or faculty consultative bodies (facultaire overlegorganen) recognized by Studentenraad KU Leuven as well as organisations (vrije verenigingen) recognized by LOKO or KU Leuven. We are not eligible to request SSL/TLS certificates for individuals with a personal account, nor research groups or staff associations. We suggest those latter groups request certificates from KU Leuven ICTS directly or consider Let's Encrypt or another third party service.

Before sending us a request, the following steps have to be performed:
* Set up the site that needs SSL if that's not already the case
* Make sure our nameservers are being used for the involved domain(s), as explained on [[Adding domain names]]
* Consider all subdomains (whether separate websites or not) you wish to have certificates for
* Make a list of all relevant arguments for your use of SSL/TLS certificates. It's important to consider aspects of your website where important or personal information is exchanged: registration, login pages, newsletter signup, etc.

When '''all''' steps are done, the account holder of the ULYSSIS account can send an email to ulyssis@ulyssis.org containing their name, the name of the organisation, the relevant arguments what you will use SSL for and the domain and if needed a list of subdomains that should be covered by the certificate.

Based on our previous experience and our arrangements with ICTS we will consider whether you are eligible for certificates and whether your request is well-founded. We will then generate the required cryptographic key and request and submit them on the certificate platform supplied by ICTS and its partners. Depending on the situation, the verification and delivery of the certificate can take some time. As soon as the certificate has been issued, we will install it and notify you.

For procedures to request certificates, we follow instructions from ICTS. These instructions have changed several times in the past, so it's possible for a new request or for a renewal, you may have to follow a different procedure or make changes.

{{notice|Limitations|ICTS does not allow SSL requests for historic *.student.kuleuven.be domains. We judge requests for username.ulyssis.be and username.studentenweb.org on an individual basis.}}

==External certificates==
To install external certificates we require the certificate itself, the private key, and possibly the chain. We prefer you also send us (a link to) the documentation of your supplier. As certificate files, especially private keys, are a delicate matter we suggest you just email us the path in your homedirectory you've put them and we will move them over to the webserver safely. For more information concerning this procedure you can always contact us on ulyssis@ulyssis.org

===Let's Encrypt===
We currently do not have an automated system for renewing and deploying certificates such as those supplied by Let's Encrypt. We are however looking into automating this process in the future. Since more of our users are starting to use Let's Encrypt, and all of their certificates need to be renewed frequently, we have a specific procedure now.

When wishing to add a certificate with Let's Encrypt to your website, or renew your existing one, first create a folder <code>letsencrypt</code> in your '''home directory'''. Then add a folder per domain or group of domains:

mkdir -p ~/letsencrypt/mydomain.be

Certificates should be stored in these folders, according to the following file structure:

letsencrypt/
└── mydomain.be/
├── mydomain.be.chain (the CA file)
├── mydomain.be.crt (the cert file; "public key")
└── mydomain.be.key (the key file; "private key")

If you already possess the necessary files, renaming and copying them accordingly is sufficient.
'''You still have to email us to install your certificate.''' More information in the last section on this page.

Otherwise, you can generate or renew your certificates using acme.sh. This is explained in the next section.

==== Generating certificates ====
{{notice|If you use a <code>.htaccess</code> file in the webroot of the domain name, make sure to add the following lines at the top of the file:|<pre><IfModule mod_rewrite.c>
RewriteRule "^.well-known/acme-challenge" - [L]
</IfModule></pre>}}
Because the normal method of generating Let's Encrypt certificates, certbot, requires root access, it's impossible for normal users to do so on our servers. Luckily there are plenty of alternatives which implement the Let's Encrypt protocol. In this tutorial, we'll show how to use the acme.sh program to generate certificates on the ULYSSIS servers. '''If you already followed this section to generate certificates, skip to the next section on renewing certificates.'''

Firstly, execute the following commands to download the acme.sh script in your home directory and make it executable:

curl -o ~/acme.sh https://raw.githubusercontent.com/acmesh-official/acme.sh/master/acme.sh
chmod +x ~/acme.sh

Next, determine for which domains and subdomains you want to generate a certificate. You will need to generate a single certificate for each domain and subdomain which points to the same folder on your account (in most cases this is <code>www</code> in your home directory).

The following example command will generate a certificate for <code>mydomain.be</code> and <code>www.mydomain.be</code> which points to the <code>www</code> folder in the home directory. '''Change the parameters''' as explained below before executing this command!

~/acme.sh --issue --cert-file ~/letsencrypt/mydomain.be/mydomain.be.crt --key-file ~/letsencrypt/mydomain.be/mydomain.be.key --ca-file ~/letsencrypt/mydomain.be/mydomain.be.chain -m "email@mydomain.be" -w ~/www -d mydomain.be -d www.mydomain.be --server letsencrypt

The explanation of these many parameters is as follows:
* <code>--issue</code> tells acme.sh to generate a new certificate.
* <code>--cert-file ~/letsencrypt/mydomain.be/mydomain.be.crt</code> tells acme.sh to store the certificate file in the <code>letsencrypt/mydomain.be</code> folder in your home directory, using the special file name as required by the file structure. '''This folder should already exist''', please refer to the previous section if you have not created this folder yet.
* <code>--key-file ~/letsencrypt/mydomain.be/mydomain.be.key</code> tells acme.sh to store the key file in the <code>letsencrypt/mydomain.be</code> folder in your home directory, using the special file name as required by the file structure.
* <code>--ca-file ~/letsencrypt/mydomain.be/mydomain.be.chain</code> tells acme.sh to store the CA file in the <code>letsencrypt/mydomain.be</code> folder in your home directory, using the special file name as required by the file structure.
* <code>-m "email@mydomain.be"</code> tells acme.sh the email address associated with the certificate. Let's Encrypt will remind this email address (if provided) when the certificate is close to expiring.
* <code>-w ~/www</code> tells acme.sh where the domains in this certificate point to. Make sure to change the <code>www</code> part if the domains point to a different folder in your home directory.
* <code>-d mydomain.be</code> and <code>-d www.mydomain.be</code> tell acme.sh that the certificate should protect <code>mydomain.be</code> and <code>www.mydomain.be</code>. The first domain name will be the "main domain", which is important for renewing. You should '''add all domain names''' pointing to the <code>-w</code> folder.
* <code>--server letsencrypt</code> tells acme.sh to use https://letsencrypt.org/ as Certificate Authority (CA).

After executing this command with the right parameters, your certificate should be generated successfully. When you have to renew the certificate in the future, you should follow the instructions in the next section. '''Don't forget to email us to install your new certificate.''' More information in the last section on this page.

==== Renewing certificates ====
To renew the certificates of <code>mydomain.be</code>, just execute:
~/acme.sh --renew -d mydomain.be

For the <code>-d</code> parameter, you have to provide the '''first''' domain name you provided when generating the certificate (in the previous section, this was <code>mydomain.be</code>.

If you are not sure which domain name to use, you can execute the command:
~/acme.sh --list

This will generate a list of available certificates, which looks a bit like this:
Main_Domain KeyLength SAN_Domains CA Created Renew
mydomain.be "" www.mydomain.be LetsEncrypt.org ... ...
... ... ... ... ... ...

In this example, the main domain is <code>mydomain.be</code>.

The renewed certificates will automatically be copied to the files you provided in the command to generate the certificates (see previous section).

'''After renewing the certificate, you have to email us to install your certificate.''' More information in the next section.

==== Getting your certificates installed ====
Check whether everything is stored correctly by executing the following command:
ulyssis-certificate check mydomain.be

If everything looks good, you should only see lines starting with <code>[ OK ]</code>. Any line starting with <code>[FAIL]</code> or <code>[ABRT]</code> means a check has failed, you must correct this error before asking us to install your certificate.

Once all steps are done and if you are the '''account holder''', '''you can send us an email clearly stating the account name, for which domains we need to add certificates and where the files are stored'''. If you are renewing existing certificates, also clearly state that in your email.

We have largely automated the installation of certificates. If you do not follow these instructions, your request will be denied or you may end up with broken SSL, so make sure you follow this procedure carefully.

[[Category:Webserver]]

Accessing your files

2021-07-20T22:22:30Z

Wtas: Completely overhauled the page

This documentation article will explain how to to upload, download, move and delete files on your account using a graphical user interface. If you are a more advanced user, you may want to use the command line to administer your files, in that case [[Accessing shell servers over SSH]] is probably a more relevant documentation page for you.

Many different SFTP clients are available depending on your needs and what operating system you run on your computer. For Windows and Mac users, we recommend the graphical SFTP client [https://cyberduck.io/download/ Cyberduck]. If you're using Linux, your file manager usually has a built-in option to connect using the details mentioned in [[#Connecting | Connecting]].

==Connecting==

{{notice|Keep in mind|Our automatic security systems may temporarily prevent you from connecting over SSH/SFTP if you try to connect several times with the wrong username and/or password. This will result in the connection being refused. You can switch between sftp://ssh1.ulyssis.org and sftp://ssh2.ulyssis.org when this happens or wait 10 minutes. More information on our security measures is available on [[ULYSSIS security measures]]}}

A Cybderduck-specific explanation can be found at [[#Connecting_2 | Cyberduck: Connecting]]. To access your files using another program you will have to enter the following connection details:
* Protocol: SFTP
* Server: "ssh1.ulyssis.org" or "ssh2.ulyssis.org"
* Port: 22
* Username: your ULYSSIS account username, the one you use for [https://ucc.ulyssis.org ucc.ulyssis.org]
* Password: your ULYSSIS account password

On our servers, your files are stored in your home folder located at <code>/home/(group)/(username)/</code>, where the group depends upon your account type and the username is your ULYSSIS account username. Any regular user is stored within the <code>user</code> group, and their files are stored within <code>/home/user/(username)</code>. For organizations, <code>org</code> is used, so files are stored within <code>/home/org/(username)</code>. Most (S)FTP clients will by default display your own home folder after you've logged in.

==Using Cyberduck==
To get started, download [https://cyberduck.io/download/ Cyberduck] from the official website. You can then install the downloaded file like you would install any other application. Once installed, launch Cyberduck and connect using the steps below.

=== Connecting ===
<ul>
<li>Click on Open Connection in the top-left corner.</li>
<li>Protocol (upper dropdown menu): "SFTP (SSH File Transfer Protocol)"</li>
<li>Username: your ULYSSIS account username, the one you use for [https://ucc.ulyssis.org ucc.ulyssis.org]</li>
<li>Password: your ULYSSIS account password</li>
<li>Server: "ssh1.ulyssis.org" or "ssh2.ulyssis.org"
<li>Enable "Save Password" if you don't want to enter your password every time you want to connect using this computer</li>
<li>Press connect</li>
</ul>[[File:Open-connection-WB.png|alt=|left|frame]]

If you get a dialog window about an unknown fingerprint, tick the "Always" box in the bottom left and then click allow. You will now be connected and able to access your files.
[[File:Fingerprint dialog window.png|none|alt=|frame]]

When you connect to a server using Cyberduck, the remote files will appear:
[[File:Cyberduck connection interface.png|none|alt=|frame]]

===Navigating===
You can open a folder by double-clicking it.
To go back up one step you can press the "Up" button to the right of the "Current Folder" dropdown.
To go back up multiple steps you can click on the "Current Folder" dropdown and select which folder you would like to go back to.[[File:Navigating-WB.png|none|alt=|frame]]

===Viewing hidden files===
To make hidden files, whose filename always start with a '.', visible, click on View -> Show Hidden Files. This is necessary because some files like ".htaccess" and ".user.ini" are hidden by default and they need to be edited sometimes.
[[File:Hidden Files.png|none|thumb]]

===Uploading files and folders===
To upload a file or folder, you can use the "Upload" button in the top menu bar and select the file or folder you wish to upload using your file manager.
[[File:Cyberduck-upload-button.png|alt=|frame|left]]

Or you can drag and drop it from your file manager (Explorer for Windows, Finder for Mac) into the current folder in Cyberduck.
[[File:Upload-drag-WB.png|none|alt=|thumb|514x514px]]

===Downloading files and folders===
To download files and folders, you can drag and drop it into your file manager (Explorer for Windows or Finder for Mac), just like uploading but in the other direction.
For files specifically it's also possible to simply double-click the file. This will then download it to your Downloads folder.

===Creating and Deleting files and folders===
To create a folder, you right click where you want your folder to be located and then click the "New Folder" option as seen below. You can then type a name for your new folder.

To create a file, you right click in the folder where you want your file to be located and then click the "New File" option as seen below. You can then type a name for your new file, making sure to include the necessary extension (eg. file.txt for a text file, file.php for a PHP file, etc.).

You can delete a file or folder by selecting it and then either pressing the "Delete" key on your keyboard, or right-clicking and selecting "Delete".
[[File:Delete-cyberduck-WB.png|alt=|thumb|384x384px|none]]

===Editing files===
Cyberduck allows you to edit files remotely by selecting a file and then pressing the "Edit" button in the top menu bar, next to the "Upload" button. This opens the file in your text editor (by default Notepad for Windows and TextEdit for Mac). After you're done editing, make sure to save the file using the text editor and then close it.
[[File:Edit.png|none|alt=|frame]]

[[Category:Files]]
[[Category:Shell]]

File:Hidden Files.png

2021-07-16T10:58:07Z

Wtas:

Show Hidden Files toggle

File:Navigating-WB.png

2021-07-16T10:56:53Z

Wtas: Wtas uploaded a new version of File:Navigating-WB.png

Navigating in Cyberduck

File:Navigating-WB.png

2021-07-02T23:17:49Z

Wtas: Wtas uploaded a new version of File:Navigating-WB.png

Navigating in Cyberduck

File:Upload-drag-WB.png

2021-05-16T20:32:29Z

Wtas: Wtas uploaded a new version of File:Upload-drag-WB.png

picture to explain dragging a file to upload it

File:Upload-drag-WB.png

2021-05-14T14:29:38Z

Wtas: Wtas uploaded a new version of File:Upload-drag-WB.png

picture to explain dragging a file to upload it

File:Edit.png

2021-05-14T02:13:36Z

Wtas: Wtas uploaded a new version of File:Edit.png

Edit a file in cyberduck

File:Delete-cyberduck-WB.png

2021-05-14T02:10:24Z

Wtas: Wtas uploaded a new version of File:Delete-cyberduck-WB.png

Delete in cyberduck

File:Navigating-WB.png

2021-05-14T02:03:29Z

Wtas: Wtas uploaded a new version of File:Navigating-WB.png

Navigating in Cyberduck

File:Cyberduck-upload-button.png

2021-05-14T01:52:03Z

Wtas: Wtas uploaded a new version of File:Cyberduck-upload-button.png

upload button for Cyberduck

File:Cyberduck connection interface.png

2021-05-14T01:47:59Z

Wtas: Wtas uploaded a new version of File:Cyberduck connection interface.png

Connection interface for Cyberduck

File:Fingerprint dialog window.png

2021-05-14T01:45:01Z

Wtas: Wtas uploaded a new version of File:Fingerprint dialog window.png

dialog window asking to trust a fingerpint

File:Open-connection-WB.png

2021-05-14T01:44:07Z

Wtas: Wtas uploaded a new version of File:Open-connection-WB.png

open a connection dialog

File:Edit.png

2021-05-02T22:21:37Z

Wtas:

Edit a file in cyberduck

File:New-file-folder.png

2021-05-02T21:52:18Z

Wtas: Wtas uploaded a new version of File:New-file-folder.png

New files and folders

File:Delete-cyberduck-WB.png

2021-05-02T21:48:28Z

Wtas:

Delete in cyberduck

File:Delete-cyberduck.png

2021-05-02T21:46:17Z

Wtas:

Delete something in Cyberduck

File:New-file-folder.png

2021-05-02T15:13:04Z

Wtas:

New files and folders

File:Navigating-WB.png

2021-04-25T16:37:08Z

Wtas:

Navigating in Cyberduck

File:Download-grab-WB.png

2021-04-25T16:24:09Z

Wtas:

download grab with blur

File:Open-connection-WB.png

2021-04-25T16:16:26Z

Wtas:

open a connection dialog

File:Upload-drag-WB.png

2021-04-25T15:41:55Z

Wtas:

picture to explain dragging a file to upload it

File:Cyberduck-upload-button.png

2021-04-25T15:22:33Z

Wtas:

upload button for Cyberduck

File:Fingerprint dialog window.png

2021-04-25T15:07:37Z

Wtas:

dialog window asking to trust a fingerpint

File:Bookmark-select-WB.png

2021-04-25T15:04:52Z

Wtas:

bookmark select with blur

File:Cyberduck connection interface.png

2021-04-14T15:14:02Z

Wtas: Wtas uploaded a new version of File:Cyberduck connection interface.png

Connection interface for Cyberduck

File:Cyberduck connection interface.png

2021-04-14T15:09:21Z

Wtas:

Connection interface for Cyberduck

File:CyberduckAddBookmark.png

2021-04-13T15:00:08Z

Wtas:

Adding a bookmark in Cyberduck

File:CyberduckQuickConnect.png

2021-04-13T14:13:22Z

Wtas:

Quick Connect screen for Cyberduck