* Pizarro ISP UY1 Guide

The Pizarro UY1 shared hosting is as vanilla, boring, and predictable as is practical. We rent full UNIX shells in a shared hosting environment. Documentation follows.

** user caveats for webhosting

   - your user account will show up with a ~/www/ directory
   - your homedir needs to be chmod 0701
   - your www dir needs to be chmod 0750 (chmod -R 0750 ~/www/ )

** operator guide

*** new users

    emplace the following script somewhere on your path (~/bin/ is a fine place):

    ######## BEGIN NEW USER SCRIPT ########

#!/bin/sh
set -eu

# args come in as $1, $2, $3
# username is the username
# ssh_key_file is the SSH public key file customer provided
username=$1
domain=$2
ssh_key_file=$3
operator=$(who am i | awk '{print $1}')
read -s -p "new user password: " user_password
printf "\n"

# ssh-keygen fails if key is invalid, which will kill the script
ssh-keygen -lf $ssh_key_file

useradd $username
cat $ssh_key_file > /home/$username/.ssh/authorized_keys
chown $username:$username /home/$username/.ssh/authorized_keys

chmod 0701 /home/$username
chmod -R 0755 /home/$username/www

passwd $username <<EOF
$user_password
$user_password
EOF

usermod -U $username

cat << EOF > /etc/apache2/vhosts.d/$username.conf
<VirtualHost *:80>
        ServerName $domain
	ServerAlias www.$domain
        DocumentRoot "/home/$username/www"

        KeepAlive Off
        LogLevel info

        <Directory /home/$username/www>
            AllowOverride All
            Options FollowSymlinks
            Require all granted
            DirectoryIndex index.php index.html

        </Directory>

        LogLevel warn
</VirtualHost>

EOF

mysql -u$operator -p <<EOF
create database $username;
create user '$username'@'localhost' identified by '$user_password';
grant all privileges on $username.* to '$username'@'localhost';
flush privileges;
EOF

/usr/sbin/apache2 -t
/etc/init.d/apache2 reload

echo "please encrypt and relay the following to the customer:"
printf "\n"
echo "ssh -p 50022 $username@161.0.121.247"
echo "your linux and mysql passwords are both $user_password"
echo "configure applications to connect to  mysql at 127.0.0.1"
   ######## END NEW USER SCRIPT ########

   This script takes 3 arguments:
   1. username
      The name of the user, which will become their homedir, and also the name of their Apache vhost file (a la $username.conf).
   2. domain
      This script provisions users with a single domain, although there's no reason they can't have more. Provide the domain as the second argument to the script, without any prefixes. pizarroisp.net and not www.pizarroisp.net. Read the script, and you will learn that the www subdomain provisions as well.
   3. ssh key
      Before you run this script, put the new user's SSH key somewhere on the machine (~/ssh_keys/ is a fine place). This script copies their SSH key into their SSH directory and ensures correct permissions.

   Do read through the script so that you understand what it is that you're doing before you use it. Once it makes sense, run it thusly:

   sudo newuser.sh mircea_popescu trilema.com ~/ssh_keys/mircea_popescu.pub

*** routine reloads

    In cases of:
    - setting a new customer up with webhosting
    - changing customers' virtualhost configurations

    After changing any Apache configuration at all, follow this checklist:

   1. sudo /usr/sbin/apache2 -t

      This tests Apache's new configuration. If this reports errors other than:

        AH00557: apache2: apr_sockaddr_info_get() failed for UY1
        AH00558: apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.0.1. Set the 'ServerName' directive globally to suppress this message

      Followed by:

        Syntax OK

      Stop what you're doing, and revert whatever changes you made.

   2. sudo /etc/init.d/apache2 reload

      Very important to send the `reload' command and not the `restart' command, lest you terminate connections still being served among other horrors.

*** significant changes to Apache configuration

    Plan this. Know what you're going to do, write down the changes that you're going to make and how to back them out.

    Provide 24-hour notice in #pizarro, and provide a window in which you'll perform and test the changes. Provide a 1-hour heads-up, and then another when you begin work in earnest.

    Once you've effected changes, run:

    sudo /usr/sbin/apache2 -t

    and inspect the output. If it doesn't look right, stop, revert, think harder. If things look good, run:

    sudo /etc/init.d/apache2 restart

    Then visit several of the websites that we serve (mocky.org, thewhet.net, pizarroisp.net ... ) and ensure that they're up. If they're not, revert, restart Apache and figure out what you did wrong. If you cannot revert readily, note this in #pizarro and work to fix it.

    Your goal is to always have a live webserver. Take small steps and confirm that we're still up after every change. Take copious notes on the changes that you do make. If at any point you're uncertain, stop what you're doing and ask for input. Uptime uber alles.

    Once you've successfully changed server configuration, make a note of this in #pizarro, and thank the customers for their patience during maintenance.