uberspace / manual Goto Github PK

Provide documentation on Ada and gnat.

See also https://git.uberspace.is/uberspace/uberspace7/issues/979#note_37217

• we provide Erlang/OTP 20, 21, 22
• standard version Erlang/OTP 21
• change with uberspace tools version use erlang <erlangversion>
• packets build by us, minor updates will be applied automatically

In the old wiki there was documentation on how to use ports. However on Uberspace 7 the old commands uberspace-...-port family does not work anymore.

Maybe add a page to the manual about how this process is supposed to work now?

add nodejs 11 to the nodejs article :)

Since SELinux is now active (and enforced), we should mention it here. A good place might be in the article for the web document root or maybe a standalone article?

Some things I think we should mention are:

Basics

Files not only are subject to the traditional discretionary access controls (DAC) — aka file system permissions (ugo/rwxst) — but with SELinux also to mandatory access control (MAC).

This means that besides drwxr-xr-x. there is also a label, you can notice this by the . suffix. You can view the label for a file with ls -Z or stat (for example):

$ ls ~
drwxr-xr-x. janto janto unconfined_u:object_r:home_bin_t:s0 bin
drwxr-xr-x. janto janto unconfined_u:object_r:user_home_t:s0 etc
lrwxrwxrwx. root  root  unconfined_u:object_r:user_home_t:s0 html -> /var/www/virtual/janto/html
drwxr-xr-x. janto janto unconfined_u:object_r:user_home_t:s0 logs
drwx------. janto janto unconfined_u:object_r:mail_home_rw_t:s0 Maildir
drwxr-xr-x. janto janto unconfined_u:object_r:user_tmp_t:s0 tmp
drwxr-xr-x. janto janto unconfined_u:object_r:user_home_t:s0 users

BTW: the -Z switch works with a lot of commands (e.g. id -Z, mv -Z, ps -Z).

The Label

The label is the representation of a context and everything in the SELinux world has one; it decides what can be done by, with and to it.

The label has 4 fields, divided by : (the last field can have colons in it, but still, only 4 fields). These are user, role type and sensitifity. Right now we only care about the type.

So the unconfined_u:object_r:user_home_t:s0 from above has a type of
user_home_t.

Files and Labels

Files you create — in your home — generally have the user_home_t label (because they inherit the label from their parent folder). The same goes for downloaded or checked-out files, etc.

$ touch ~/test
$ ls -Z ~/test
-rw-rw-r--. janto janto unconfined_u:object_r:user_home_t:s0 /home/janto/test
$ wget -O ~/index.html google.de
$ ls -Z ~/index.html
-rw-rw-r--. janto janto unconfined_u:object_r:user_home_t:s0 /home/janto/index.html

Notice ~/bin changes the type to home_bin_t:

$ touch ~/bin/cmd.py
$ ls -Z ~/bin/cmd.py
-rw-rw-r--. janto janto unconfined_u:object_r:home_bin_t:s0 /home/janto/bin/cmd.py

Gotchas

If you create a new file, it immediately inherit the context of it's parent. This works for cp too, cause it creates new files. But not for mv, since the existing content is carried allong with the file.

$ cp ~/test ~/html/
$ ls -Z ~/html/
-rw-rw-r--. janto janto unconfined_u:object_r:httpd_sys_content_t:s0 test

But:

$ mv ~/index.html ~/html/
$ ls -Z ~/html/
-rw-rw-r--. janto janto unconfined_u:object_r:user_home_t:s0 index.html
-rw-rw-r--. janto janto unconfined_u:object_r:httpd_sys_content_t:s0 test

An easy way to cope with this is to make it a habbit to restore the parent to it's default with restorecon:

$ restorecon -Rv ~/html
restorecon reset /var/www/virtual/janto/html/index.html context unconfined_u:object_r:user_home_t:s0->unconfined_u:object_r:httpd_sys_content_t:s0
$ ls -Z ~/html
-rw-rw-r--. janto janto unconfined_u:object_r:httpd_sys_content_t:s0 index.html
-rw-rw-r--. janto janto unconfined_u:object_r:httpd_sys_content_t:s0 test

NOTICE: This is important, since Apache will throw a 403 if the content in ~/html is not labled with httpd_sys_content_t (or similar, see below for more).

Changing Labels

To set a file's context, you can use the chcon command:

$ chcon -t httpd_sys_content_rw_t ~/web-data

This change will survive a reboot. However, this does not update the SELinux user space definition list. So after a restorecon the directory will be reset to the original context.

Conclusion

Well, this is just the basics and the whole semange thing is probably not needed for users. Instead, we should mention man httpd_selinux — make sure this works on our hosts https://git.uberspace.is/uberspace/uberspace7/issues/611 — and some neccesarry types for daily operation like:

• httpd_sys_content_t: read-only directories and files
• httpd_sys_content_ra_tappend only
• httpd_sys_content_rw_t: readable and writable directories and files
• httpd_sys_script_exec_t: executable scripts
• httpd_log_t logs
• httpd_cache_t mod_cache

uberspace web backend set now supports a --remove-prefix argument. Requests to /etherpad-lite/static/foo.js, with a backend /etherpad-lite, will be proxied as /static/foo.js. Backends without that flag proxy the whole path through.

Purpose of this page is providing a sense of feeling at home quickly. It's probably the first piece of documentation new users are reading after registering an account, so it should be really well-crafted. Probably first showing support options.

• What's the same (e.g. directory structure)?
• What's different (e.g. automatic HTTPS)?
• What doesn't work anymore, and why (e.g. wildcard domains)?

Barracuda was deprecated in MariaDB 10.3.1. Add ad small hint in the MySQL article.

Choose a license! :) Probably something out of the Creative Commons Space? Or the GNU Free Documentation License, which Wikipedia uses?

$ echo "überspace.de" | idn
xn--berspace-55a.de

mention in https://github.com/Uberspace/manual/blob/master/source/includes/domain-idn.txt

Wait for U7 issue, see discussion there.

PHP 5.6 and 7.0 reached their EOL in december 2018 and will be removed fromU7 hosts.

For consistency und user experience every article about programming languages should be constructed in a streamlined way.

• All headlines should be the same
• If a topic does not apply, the headline is left out

Suggestion:

Title
#####

Introduction
============

Versions
========

Release Types 
-------------
and what to choose

Standard version
----------------
and why

Change version
--------------
and how to find out what is selected

Update Policy
-------------
which versions are provided, for how long, how fast to we phase old versions out?

Connection to webserver
=======================
How to publish
--------------

Configuration
=============
provided configuration
----------------------
additional / own configuration
------------------------------
provided extensions / modules
-----------------------------
additional extensions / modules
-------------------------------

Best practices
==============
security
--------

Known problems and caveats
==========================

Popular software
================

Problem:

Fatal error: Allowed memory size of 1610612736 bytes exhausted (tried to allocate 67108864 bytes) in phar:///usr/local/bin/composer/src/Composer/DependencyResolver/Solver.php
on line 223

Check https://getcomposer.org/doc/articles/troubleshooting.md#memory-limit-errors for more info on how to handle out of memory errors.

Lösung:

COMPOSER_MEMORY_LIMIT=-1 php /usr/local/bin/composer install

Durch die Verwendung von COMPOSER_MEMORY_LIMIT=-1 stellen Sie sicher, dass der PHP-Prozess nicht mehr Speicher als der im Parameter memory_limit zugewiesene verbraucht.

Im using this snippet to use individual document roots for my subdomains can anyone add that to the u7 manual.

For example we have these domains added to our uberspace:
uberspace.de
blog.uberspace.de
cloud.uberspace.de

each of these subdomains has its own folder(Document root):
uberspace.de = /var/www/virtual/$user/html/ (root domain)
blog.uberspace.de = /var/www/virtual/$user/blog.uberspace.de/
cloud.uberspace.de = /var/www/virtual/$user/cloud.uberspace.de/

To set the document roots accordently to the subdomains you need to add a .htacces in /var/www/virtual/$user/html/.htaccess with the following content:

RewriteBase /

RewriteEngine on
RewriteCond %{HTTP_HOST} ^(.*)\.domain\.de
RewriteRule ^(.*)$ subdomains/%1/$1 [L,NC,QSA]

As we have perl-core (the set of standard Perl modules) and perl-App-cpanminus (a modern package manager) installed, our Perl setup is usable for most tasks. We need some documentation for it.

• Versioning: Explain why we offer Perl 5.16 despite it being already end-of-life (but gets backported updates by Red Hat)
• Refer to perlbrew as an alternative to install your completely own (and thus unsupported) Perl
• Explain cpanm to install Perl modules from CPAN
• If user-installed modules are used, a single line has to be added to the .bashrc - but we should probably do this centrally on our side
• Apart from the docs we can write a guide or two on how to create a basic application with the Catalyst or Mojolicious framework

Here's the test from U7.4:

Feature: Setup spam folder
    As a Uberspace user
    I want to be able to sort my spam into a seperate folder
    So that I can keep my inbox spam free

    Background: Uberspace account exists
        Given I have a Uberspace account with a password
        And I am logged into the shell
        And I have a mailbox named "mymailbox"

    Scenario: use spamfolder commands to controll filtering

        # Check default

        When I input "uberspace mail spamfolder status"
        Then the output begins with:
            """
            The spam folder is disabled.
            """

        # Disable filter

        When I input "uberspace mail spamfolder disable"
        Then the output begins with:
            """
            The spam folder is already disabled.
            """
        When I input "uberspace mail spamfolder status"
        Then the output begins with:
            """
            The spam folder is disabled.
            """
        When I input "cat .qmail-default"
        Then the output contains:
            """
            /usr/bin/vdeliver
            """

        When a mail with an RSPAM score of "3" with subject "maybe SPAM" is sent to my mailbox
        And a mail with an RSPAM score of "10" with subject "surely SPAM" is sent to my mailbox

        When I look for the mails in my mailbox
        Then I can find a mail with subject "maybe SPAM"
        And I can find a mail with subject "surely SPAM"

        When I look for the spam in my mailbox
        Then I can't find a mail with subject "maybe SPAM"
        And I can't find a mail with subject "surely SPAM"

        # Enable filter

        When I input "uberspace mail spamfolder enable"
        Then the output begins with:
            """
            The spam folder is now enabled.
            """
        When I input "uberspace mail spamfolder enable"
        Then the output begins with:
            """
            The spam folder is already enabled.
            """
        When I input "uberspace mail spamfolder status"
        Then the output begins with:
            """
            The spam folder is enabled.
            """
        When I input "cat .qmail-default"
        Then the output contains:
            """
            spamfolder
            """

        When a mail with an RSPAM score of "3" with subject "maybe SPAM too" is sent to my mailbox
        And a mail with an RSPAM score of "10" with subject "surely SPAM too" is sent to my mailbox

        When I look for the mails in my mailbox
        Then I can find a mail with subject "maybe SPAM too"
        And I can't find a mail with subject "surely SPAM too"

        When I look for the spam in my mailbox
        Then I can't find a mail with subject "maybe SPAM too"
        And I can find a mail with subject "surely SPAM too"

        # Disable filter again

        When I input "uberspace mail spamfolder disable"
        Then the output begins with:
            """
            The spam folder is now disabled.
            """


    Scenario: keep existing .qmail-default if it contains user-changes
        Given I have a file named "/home/<username>/.qmail-default" with the following content:
            """
            my own config
            """

        When I input "uberspace mail spamfolder enable"
        Then the output contains:
            """
            we don't touch it
            """
        When I input "cat .qmail-default"
        Then the output contains:
            """
            my own config
            """

        When I input "uberspace mail spamfolder disable"
        Then the output contains:
            """
            we don't touch it
            """
        When I input "cat .qmail-default"
        Then the output contains:
            """
            my own config
            """

Give users an overview how to manage email addresses / aliases with .qmail files:

• what is qmail? (is fairly non-standard, so explain it)
• how do I forward my primary mail address to something external? to another address (hello@ => hallo@)?
• how do I forward secondary mailboxes? to another address? (link to vmailmgr)
• how do I drop all mail to an address?
• how do I configure a wildcard box?

Windows 10 since "Fall Creators Update" (version 1709) comes with an OpenSSH client preinstalled. This can be used from both Command Prompt and Power Shell, no puTTY needed any more. I went through the Unix/Linux steps for SSH, and they all work as expected, including the SHA256 fingerprint display of the host upon first connection.

I suggest to change the wording in the appropriate part of the manual to also refer to these modern versions of Windows 10. Also see this German Twitter thread from November 29, 2019.

Maybe add automatic style checks, e.g. with write-good.

E.g.

FROM node:10
RUN yarn global add write-good
WORKDIR /app
ENTRYPOINT ["write-good"]
CMD ["--help"]

And run it like:

docker run --rm -it -v "$(pwd)":/app ubrs/write-good source/*.rst

Explanations of all possible options, like suggested would be nice.

Right now the change log is reeeeeallyyyyy long. It would be nice to split that up into 7.0.x and 7.1.x and so on, each on separate pages.

Create and implement a nice and shiny 404 page for lost users with a link back to the main page.

Since we switched to netlify for building the manual, a few things changes:

• make the README way more friendly
• the documented preview domain is no longer valid, use netlify URLs
• we need python 3.6

We install a bunch of extra software like mosh or imagemagick on our serves. Compile a list (maybe in an automated way?) and show it to our users publicly.

https://git.uberspace.is/uberspace/uberspace7/blob/master/roles/user_tools/tasks/package.yml

At the moment, Sphinx's search results show raw source snippets. Try to make them prettier, possibly using https://github.com/TimKam/sphinx-pretty-searchresults

Add a new language article for golang:

• only the newest version
• explain GOPATH a little, link to further docs

Merge only after v7.3.0.

https://manual.uberspace.de/en/changelog.atom ends in a 404.

See https://twitter.com/schoetzau/status/1109166333466460160

Composer has been installed for a while now, but is missing an article.

Composer installs packages relative to the current directory (or the composer.json file respectively). Users can also install packages user-global instead — e.g. composer global require packagex. In this case composer creates links to binaries included in the installed package in ${HOME}/.config/composer/vendor/bin. When this is merged, the ${HOME}/.config/composer/vendor/bin path is added to the users PATH environment variable, so user-global binaries can be run without their path.

The content is licensed as CC-BY-SA-NC, as noted in the LICENSE file and README. Also put this information into the rendered footer, as we do for the manual.

so I wrote up some examples for maildrop filtering, find them here and feel free to incorporate them. https://github.com/kaerf/manual/blob/master/source/mail-filter.rst

any file or directory whose path includes the string no_backup will get excluded from backups. Update manual accordingly.

Uberspace/lab#244

The current "for newbies" intro is more of a placeholder and not actually that helpful. A user suggested a quickstart guide like that:

1. setup SFTP client
2. where to find SFTP login data
3. select html folder, upload files
4. how to access the website

This resembles quite much the workflow for users coming from other shared hosting providers, even if we aim at the use of the shell instead, e.g. using wp-cli to download and install WordPress instead of navigating the WP website, download a file to your local computer, unzipping it, uploading all the files... which is way more cumbersome but the way many people are used to do it and while we want to educate them, we still want them to achieve quick results.

We install java on U7 hosts, so document that.

https://twitter.com/Snapstromegon/status/1126576031912157184

• remove node 9
• check all other tools/versions

http://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_push_preload

• think about which section to put h2 push headers
• add a very basic .htaccess example?
• link to further docs (preferably not just the spec, as nginx does.. maybe MDN?)

We should document our "domain rules".

Current state on U7: After a user successfully registered a domain (with uberspace <web|mail> domain add …) neither the domain nor any sub domain of it can can be registered by any other user on that host (regardless of the type, i.e. web / mail). This is in contrast to U6, where different users can have access to the same domain, if different types (web / mail) are used.

Make it easy for people to edit the manual and easy for us to accept their changes. Document how we'd like to do things.

See https://github.com/Uberspace/lab/blob/master/CONTRIBUTING.md

https://haraka.github.io/manual/plugins/early_talker.html

Our mailservers are slow, but hat's a feature to block spammers. Add that as a tip or info box.

See https://git.uberspace.is/uberspace/uberspace7/merge_requests/544#note_17311

How are the priorities? Which binaries are executed? How can I override it?

The next U7 release will allow setting variables in ~/.ssh/environment and ~/.ssh/authorized_keys. Extend the SSH article to explain document that we support that.

https://git.uberspace.is/uberspace/uberspace7/blob/master/roles/openssh/README.md

Make the manual available at http://manual.uberspaceyukm42r.onion/