K2
From Worms Knowledge Base
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! |
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 at https://pma.k3.1azy.net/. You can log in with your username and MySQL password (which is different from your account password).
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.
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 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.
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.
