Difference between revisions of "K2"
From Worms Knowledge Base
CyberShadow (Talk | contribs) (Formatting; add default domain example) |
CyberShadow (Talk | contribs) m (Formatting) |
||
Line 31: | Line 31: | ||
* <code>~/.k2</code> - Your ''k2system'' configuration (details below). | * <code>~/.k2</code> - Your ''k2system'' configuration (details below). | ||
− | * <code>~/www</code> - Website root. You can place your .html and .php files here. | + | * <code>~/www</code> - Website root. You can place your <code>.html</code> and <code>.php</code> files here. |
* <code>~/k2-data</code> - Symlink to your personal data directory on the server's hard drive. | * <code>~/k2-data</code> - Symlink to your personal data directory on the server's hard drive. | ||
* <code>~/k2-scratch</code> - Symlink to your personal scratch directory on the server's hard drive (not backed up). | * <code>~/k2-scratch</code> - Symlink to your personal scratch directory on the server's hard drive (not backed up). | ||
Line 124: | Line 124: | ||
=== Domains === | === Domains === | ||
− | By default, your website is accessible via the server's wildcard DNS entry (*.k3.1azy.net). If your UNIX (SSH login) username is ''alice'', the website can be accessed at | + | By default, your website is accessible via the server's wildcard DNS entry (*.k3.1azy.net). If your UNIX (SSH login) username is ''alice'', the website can be accessed at https://alice.k3.1azy.net/. |
If you would like to add a nicer hostname to your website, do the following: | If you would like to add a nicer hostname to your website, do the following: |
Revision as of 21:17, 11 March 2023
This page contains the documentation of k2system, a management and administration system for user accounts. It is used on the same server as the one serving this very web page.
The system does not impose quotas or hard limitations, and instead depends on the good will and technical competency of all users. Please take care to not abuse it - careless abuse of resources will negatively affect all other users and services. Thanks! |
This system is relatively unusual, and many components are custom. For this reason, blindly following guides from the Internet will not work. Do not copy and paste commands or configuration files without fully understanding them and how they will interact! Instead, if something is unclear, contact an administrator. |
Contents
Logging in
Remote access, administration, and file management is done over SSH. This means that you can use any SSH client to log in to an interactive shell, or use any standard SSH-based file transfer programs (such as scp, sftp, rsync). On Windows, you can use PuTTY for SSH access, and WinSCP for file management.
Although you may change either password, please use only very strong passwords. Failure to do so will make your account susceptible to brute force attacks (which are happening constantly), which may lead to the entire server being compromised. |
If you don't want to type a password every time you log in, you can configure a SSH key. Please do not use any software which "remembers" passwords, as malware frequently targets configuration files of such software, which will lead to your account being compromised.
A phpMyAdmin instance is available; see #MySQL.
Overview
Hosting and resource partitioning is done as follows:
- Generally, each website or service runs as its own UNIX user, and has its personal home directory at
/home/username
. - Each user runs their own local web server, listening on port 81 and their personal private local IP address (
127.42.x.y
).
- (
authbind
is used to allow listening on port 81 and prevent one user from hijacking another user's HTTP port).
- All incoming web requests are first accepted by reverse proxies, for both HTTP and HTTPS, and then distributed to the appropriate user according to their configured domain list.
- A shared MySQL instance allows database storage. Each user has their personal MySQL database.
- Symlinks in the home directory point to users' personal directories on the data, scratch, and fast-scratch storage volumes.
Directory layout
New accounts start with a home directory with the following layout:
-
~/.k2
- Your k2system configuration (details below). -
~/www
- Website root. You can place your.html
and.php
files here. -
~/k2-data
- Symlink to your personal data directory on the server's hard drive. -
~/k2-scratch
- Symlink to your personal scratch directory on the server's hard drive (not backed up). -
~/k2-fastscratch
- Symlink to your personal scratch directory on the server's SSD (not backed up).
How to place files
Please follow these rules when uploading or creating files on the server.
- If a file is large or accessed very infrequently, and you can easily recreate or re-upload it should it be lost, place it under
~/k2-scratch
.
Examples:- Files you downloaded from the Internet.
- Large temporary files.
- Your personal backups. (The other copy is on your computer, right?)
- If a file is large or accessed very infrequently, and it cannot be easily recreated or re-uploaded place it under
~/k2-data
.
Examples:- Photos and videos that your users uploaded to your website
- If the file is small or accessed frequently, and you can easily recreate or re-upload it should it be lost, place it under
~/k2-fastscratch
.
Examples:- Temporary files, such as PHP session files.
- Logs (if you don't care about them).
- Other files should be placed in your home directory.
Examples:- The source code for your website.
Please make sure to not place large files in your home directory outside the above-described special directories. Doing so wastes precious SSD space and increases the size of our backup archives, which affects all users. |
Configuration
All configuration is done by editing the contents of the ~/.k2
directory, and then running a command (usually k2-update
or k2-service restart -a
) to apply the changes.
Web Server
You can use any web server software you like. The web server runs in your user account.
The default configuration is to use Apache, which allows familiar configuration using .htaccess
and .htpasswd
files.
Note that k2system will stop Apache if it doesn't receive a request in over an hour, which is why you may not always see it in the process list. It is automatically started back up when a request arrives.
Apache
The configuration for your personal Apache instance is located in ~/.k2/apache2
.
By default, the configuration consists of a number of symlinks to the default k2system configuration files. If you would like to edit a configuration file, you will first need to replace the symlink with a copy of the file that the symlink pointed to. For your convenience, a delink
command exists which does this. For example:
delink .k2/apache2/conf.d/site.conf mcedit .k2/apache2/conf.d/site.conf
By default, only a small number of modules are enabled (see ~/.k2/apache2/mods.d
). To enable a new module, you can create a symlink pointing to the corresponding file in the k2system default configuration. Example:
ln -s /usr/local/etc/k2/apache2/mods.d/cgi.load .k2/apache2/mods.d/cgi.load
To disable a module, simply delete the symlink.
Finally, to apply changes to the configuration, run k2-service restart -a
.
Cherokee
Not documented.
lighttpd
Not documented.
PHP
PHP is configured in a similar manner as Apache:
- php.ini is located in
~/.k2/php/php.ini
. By default, it is a symlink to/usr/local/etc/k2/php/php.ini
. - PHP modules can be enabled by creating symlinks in
~/.k2/php/conf.d
.
MySQL
Your MySQL database password is different from your login password, and was sent to you by email during registration.
To access the database from your website, you can use the following credentials:
- Hostname:
localhost
or blank - Username: your SSH login username
- Password: your MySQL password
- Database: your SSH login username
For an interactive SQL prompt, simply run mysql
from a SSH command line.
The MySQL client is preconfigured with your credentials (see ~/.my.cnf
).
To dump the entire database, you can run e.g.: mysqldump your-username > database.sql
A phpMyAdmin instance is available at https://pma.k3.1azy.net/. You can log in with your username and MySQL password.
Logs
Apache logs (access and error) are, by default, placed in ~/.k2/apache2/logs
.
Log rotation is configured in the ~/.k2/logrotate.template
directory. By default, Apache logs are rotated weekly.
Domains
By default, your website is accessible via the server's wildcard DNS entry (*.k3.1azy.net). If your UNIX (SSH login) username is alice, the website can be accessed at https://alice.k3.1azy.net/.
If you would like to add a nicer hostname to your website, do the following:
- Point the hostname to the server's IP address
- Create a file in
~/.k2/domains
named after the hostname (e.g. if you would like to use "you.example.com", create~/.k2/domains/you.example.com
) - Run
k2-update
to tell k2system to update the server configuration.
DNS
You can also host your DNS zone on the server. To do so, create a zone file (in standard BIND syntax, with a .hosts
extension) in ~/.k2/dns
, and run k2-update
.
For your convenience, k2system also understands a file format with a .hosts-template
extension, which allows substituting variables which apply to all domain names. As such, the easiest way to add a zone is to create ~/.k2/dns/hostname.hosts-template
with the following contents:
$TTL 38400 ; default expiration time of all resource records without their own TTL value %DOMAIN%. IN SOA %SERVERHOST%. %USER%.%SERVERHOST%. ( %MODTIME% ; serial number of this zone file 21600 ; slave refresh (in seconds) 3600 ; slave retry time 604800 ; slave expiration time 86400 ; maximum caching time in case of failed lookups ) IN NS %SERVERHOST%. IN NS %DNS2%. IN MX 10 mail.%DOMAIN%. IN A %SERVERIP4% IN AAAA %SERVERIP6% mail IN A %SERVERIP4% mail IN AAAA %SERVERIP6% www IN CNAME @
The server does not store email, so there are no mailboxes to check (or access via POP3/IMAP or otherwise). However, redirects can be configured.
Assuming that your DNS MX records are set up to point to the server's IP addresses, email will be accepted for the domains you configured (in ~/.k2/domains
). To configure what happens to mail sent to localpart@your-domain.com
, create the file ~/.k2/mail/aliases/localpart
. It can contain an email address to redirect to, or /dev/null
to discard all email. See the exim documentation for more details. If a file corresponding to the local part does not exist, the file named default
is consulted instead.
Internally generated mail is sent to the email address indicated in the ~/.email
file.
Note that the files in the aliases directory must have mode 644
. (Depending on how you log in, they may be instead created with mode 664
.) Use chmod
to change it.
Make sure to run k2-update
to apply changes in ~/.k2/mail
.
Please do not configure redirects for email addresses which receive a lot of spam. Doing so negatively affects the reputation of the server's IP address, which eventually leads all sent and redirected mail to be marked as spam. If you receive a large amount of mail, please use a professional (paid) email service. |
SSL
This section describes how to configure SSL for HTTP (i.e., HTTPS). By default, attempting to access your website via HTTPS will use the server's wildcard certificate, which will cause most user agents to display a warning or error.
Bring Your Own Certificate
If you already have an SSL certificate for your domain and would like to use it, place the files in the ~/.k2/ssl
directory as follows:
-
~/.k2/ssl/site.pem
- your certificate -
~/.k2/ssl/chain.pem
- your SSL provider's certificate -
~/.k2/ssl/site.key
- your certificate's private key
Let's Encrypt
Unless you already have an SSL certificate, the easiest way to enable SSL is using the free Let's Encrypt certificate provider. Simply run k2-letsencrypt
to enable SSL for your configured domains.
Note: k2-letsencrypt
does not work with the default *.k3.1azy.net wildcard hostnames. You will need to add a different hostname to enable SSL for your website.
Redirect to HTTPS
You can redirect clients which opt-in to SSL to HTTPS by placing the following in ~/www/.htaccess
:
# Redirect to HTTPS clients indicating their preference for it # Note: this should also send a Vary header, but doesn't due to Apache bug RewriteCond %{HTTP:Upgrade-Insecure-Requests} ^1$ RewriteCond %{HTTP:X-Scheme} !https RewriteRule ^(.*)$ https://%{HTTP_HOST}/$1 [R,L]