test

[hcoop/zz_old/ikiwiki] / MemberManual / MigrationGuide.mdwn

## page was renamed from MigrationTips\r
For the purposes of this page, we'll use the name New to refer to the servers hosted at Peer 1 (which are deleuze, mire, and eventually abulafia and krunk) and Old to refer to any servers that we've used previously.\r
\r
= Status of Migration =\r
'''14 September 2007''': Migration has begun!  Use this page to learn how to create a new account and migrate your data.  A user creation script will be run periodically each day.\r
\r
[[TableOfContents()]]\r
\r
= Summary of what exactly is going on here =\r
\r
We are now offering limited-access accounts on the new infrastructure (see NewServersSetup) on a "beta test" basis to all users who have accounts on fyodor. These accounts come with no uptime or service guarantee; during the next few weeks we may need to temporarily disable them from time to time.    Please keep all of your original data on Fyodor in the event something unexpected happens.  \r
\r
These accounts will allow you full access to your space in AFS (currently 400MB per user) and the ability to log in to mire.hcoop.net via ssh.  Currently NO OTHER SERVICES are officially supported on the new infrastructure (for example, email or serving HTTP), although they do work.\r
\r
Requesting an account on the new infrastructure will not affect your fyodor account.  You will have access to both accounts until after all migration is complete.\r
\r
= Getting started =\r
\r
== Step 1: Get a New account ==\r
\r
 1. ssh to `hcoop.net` as usual.\r
 1. Run this command line: `migrationpw`\r
 1. Follow the on-screen directions.\r
 1. Wait for an e-mail from the user creation script.  (This stage requires that a human run the script periodically to watch for failures, but one of us should run it several times a day.)\r
\r
The password you set will go into our new Kerberos database, allowing log-in to mire and any other of our servers that we choose to enable for non-admin shell access.  You will also use this password for authentication to other services, like e-mail and members-only HCoop web sites.\r
\r
An e-mail will be sent to your HCoop account to let you know that your account has been created.  Be sure to memorize your password, as it won't be saved anywhere unencrypted once the account creation script runs!\r
\r
== Step 2: Try logging in ==\r
\r
Now you may attempt to login using your favorite SSH client or the new AJAX SSH service at http://ssh.hcoop.net/. It requires a modern browser that cooperates with AJAX.\r
\r
=== SSH Public Key is Obsoleted ===\r
\r
You can no longer use SSH public key authentication.  ["Kerberos"] authentication ("`ssh -K`") ''is'' supported, for passwordless log-in.  Some day, someone might implement the Kerberos support needed to make SSH public key auth work again.  See RealSecurity for more information on all of this.\r
\r
That being said, if you've always been typing a password to log in via SSH and don't care to do otherwise, then you don't need to bother reading this section!\r
\r
=== DenyHosts ===\r
\r
If you fail to log in correctly a few times the DenyHosts scripts will lock you out.  Currently any blocked IP's are purged after a week, so if you don't want to wait you'll need to submit a ticket, or if you can't access the portal to do this you'll need to send an email to admins@hcoop.net.\r
\r
== Step 3: Visit the new portal ==\r
\r
[https://members2.hcoop.net/ The new portal] uses the same password you use to log in to mire.  That is, if you haven't created a New account yet, then you can't access the new portal.\r
\r
You should use the new portal for all administrative requests, except for the specialized request types (e.g., domains, firewall rules, etc.) when they relate to fyodor.\r
\r
== Step 4: Have your mail dual-delivered ==\r
\r
We recommend that you tell fyodor to ''dual-deliver'' all of your mail so that one copy goes to deleuze (our new main server) and one copy goes to fyodor.  That way you can start reading your email via deleuze, but if anything goes wrong you can just switch back to fyodor.\r
\r
To do this, put the following lines in your {{{~/.forward}}} file ''on fyodor''.  Note that the comment on the first line is '''mandatory''' -- it tells exim that this forward file uses special exim features.  If your username was {{{fred}}}, you would put this in your {{{~/.forward}}}:\r
\r
{{{\r
  # Exim filter\r
  deliver fred\r
  deliver fred@deleuze.hcoop.net\r
}}}\r
\r
and you mail will be dual-delivered.\r
\r
== Step 5: Copy your existing email ==\r
\r
You can also copy the contents of your mailboxes from fyodor to mire (actually to our shared AFS filesystem by way of mire).  To do this, log in to fyodor and type the following.\r
\r
{{{\r
  rsync -are ssh --no-g --progress --verbose ~/Maildir/ mire.hcoop.net:Maildir/\r
}}}\r
\r
= Bugzilla =\r
\r
We have a [https://bugzilla.hcoop.net/ Bugzilla] that we are using for managing support requests that don't fit into the special categories handled by the portal.  If you've completed the migration steps above that create your New account, then you can use the same username and password to access Bugzilla.  You can also start from the portal, which links to Bugzilla from the support page.\r
\r
= Databases =\r
\r
''Here lie interim dbtool docs until migration is done, at which time they will probably move to UsingDatabases.''\r
\r
To manage your database user and databases, the basic syntax is `dbtool <DBTYPE> <COMMAND>`, where `<DBTYPE>` is `postgres` or `mysql`.\r
\r
The `adduser` command creates a database user for you, with the same name as your UNIX log-in name.  In the case of `mysql`, you will be prompted for a password and confirmation re-entry in the usual manner.\r
\r
The `passwd` command allows you to reset the password.  (Useless for `postgres`, where we use only ident authentication)\r
\r
The `createdb <DBNAME>` command creates a database named `<USERNAME>_<DBNAME>`, and `dropdb <DBNAME>` drops a database.  For security/accounting reasons, you won't be granted permissions to drop a database in the usual way, through an SQL session.\r
\r
Sometimes we update our policies for which permissions users are granted on their databases.  To re-set the permissions for a database after such a change, run `grant <DBNAME>`.  At the moment, this can only ever be necessary for MySQL databases.\r
\r
To access your database use the following on mire: `mysql -p -h mysql <USERNAME>_<DBNAME>`  or `psql -h postgres <USERNAME>_<DBNAME>`\r
\r
= DNS =\r
\r
We are purposely not sending any DNS data from Old to New, which means that you need to change domains at your registrar if you want New to be authoritative for them.  The proper nameservers are ns1.hcoop.net and ns3.hcoop.net, in that order.  Keeping ns.hcoop.net and ns2.hcoop.net '''will not work'''.\r
\r
= Domains =\r
\r
See the DomTool page for instructions on managing your domains with the new setup.  The configuration files are in a vastly different format, but they have a better-defined syntax that should be relatively easy to understand.\r
\r
\r
= Home =\r
\r
Your home directory is now managed by AFS.  You will enter it by default when logging in to {{{mire.hcoop.net}}} via ssh.  Type {{{pwd}}} to see what the path is.  It will look like {{{/afs/hcoop.net/user/u/us/username}}}.  Some directories have been created for you already, so that they have the correct permissions for things like serving web pages and delivering mail.\r
\r
= Email =\r
\r
Our email subsystem utilizes mostly the same configuration as with the old server.  There are a few differences in user file locations and a few updates to tools.  Note that currently the utility to create the ~/Maildir directory is not available.  The ~/Maildir directory is created when your account is created.  So please do not delete the ~/Maildir directory if you value mail delivery and access.\r
\r
== .forward ==\r
\r
{{{~/.forward}}} files should have the same effect that they do with our old setup, but on the new setup they are located at {{{~/.public/.forward}}} instead of {{{~/.forward}}}. See [https://bugzilla.hcoop.net/show_bug.cgi?id=81#c2 this bug] for more.\r
\r
== IMAP ==\r
\r
SSL IMAP is available via SSL at port 993, using hostname {{{deleuze.hcoop.net}}}.\r
\r
STARTTLS IMAP is available on port 143, using hostname {{{deleuze.hcoop.net}}}.\r
\r
== POP3 ==\r
\r
POP3 access is available via SSL at port 995, using hostname {{{deleuze.hcoop.net}}}.  If you're using Thunderbird, make sure to uncheck "Use secure authentication".  Do not use port 110; it is not available, because no good way of securing normal POP3 has been found by the admins.\r
\r
== procmail ==\r
\r
The page ProcmailExample has been updated for the new setup.  Basically:\r
\r
 * Use the file {{{~/.procmail.d/procmailrc}}} instead of {{{~/.procmailrc}}}.\r
 * Write any procmail logs in {{{~/Maildir}}} rather than elsewhere.\r
 * Use appropriate values for the HOME, MAILDIR, and DEFAULT options, based on those in ProcmailExample.\r
\r
== Virtual mailboxes ==\r
\r
The `vmail` program from fyodor has been updated for the new servers.  Here's a quick run-through of how to invoke the new version.  Like before, you always invoke it with `vmail $DOMAIN $COMMAND`, which indicates that you are configuring the virtual mailboxes for domain `$DOMAIN` for which you have DomTool permissions.  The valid commands are:\r
\r
 * `list`: Print the mapping from usernames to mailbox directories for `$DOMAIN`.\r
 * `add $USER $MAILBOX`: Add a mapping from `$USER@$DOMAIN` to a Maildir directory `$MAILBOX`.  You'll be prompted to enter a password for the user, which he can then use to access IMAP, POP, or restricted SMTP services.\r
 * `passwd $USER`: Reset a virtual user's password.\r
 * `rm $USER`: Remove a mapping.  The mailbox directory remains for you to deal with as you like.\r
\r
== webmail ==\r
\r
A Squirrelmail instance for reading your email on the new servers is available at [https://mail2.hcoop.net/].\r
\r
== Spam Filtering ==\r
Use SpamAssassin as you would on the old server (Fyodor) but keep in mind the new locations of .procmailrc and .forward (see above).  For example, you can still use {{{setsa on}}} to enable spam filtering.  See UsingEmail for use instructions.\r
\r
= rsync =\r
\r
If you're using rsync to transfer data to the new servers, the "-a" option by itself won't work properly because rsync attempts to chgrp the transferred files. Use "-a --no-g" instead of "-a".\r
\r
= Security =\r
\r
See RealSecurity for some technical notes on security.\r
\r
== Securing directories ==\r
First of all, UNIX permissions carry no weight with AFS -- therefore they are useless to you.  Instead, use Access Control Lists (ACL), which are a far more powerful way of restricting access to parts of a file tree.\r
\r
That said, when a new directory is created inside $HOME, its ACL defaults to allow listing by any authenticated party on HCoop. Note that ACLs cannot be set on individual files.  They inherit the ACL from its parent directory.\r
\r
If you wish to make a directory within your $HOME completely private so that only you can list, read, and write, do this:\r
{{{\r
mkdir ~/private\r
fs setacl -clear ~/private <USERNAME> all\r
}}}\r
\r
Note that {{{-clear}}} removes any previously set ACLs and {{{<USERNAME> all}}} sets full access to the directory's contents to the specified user.  Therefore, if you have a directory in $HOME that you wish to make only accessible to you (such as ~/.ssh or ~/documents), use:\r
{{{fs setacl -clear ~/<DIRECTORY> <USERNAME> all}}}.\r
\r
If you use domtool to set up your domain, there is a way to allow {{{system:anyuser}}} only to list the contents of public_html without breaking your website(s).  By default ACLs R and L are given.  Change that in this way:  {{{fs setacl ~/public_html system:anyuser l}}}.  Now, add all permissions for the ''USER.daemon'' principle: {{{ fs setacl ~/public_html <USERNAME>.daemon all}}}.  Be aware that this only works if you use your own domain -- if you use {{{http://deleuze.hcoop.net/~USERNAME}}} to serve your files, then you '''must''' be sure that {{{system:anyuser}}} can read {{{~/public_html}}} and its subdirectories.\r
\r
If you wish to view the ACLs on a specific directory, such as any you have just applied an ACL, use:\r
{{{fs listacl <DIRECTORY>}}}\r
\r
== Log-In Security ==\r
\r
We use the [http://denyhosts.sourceforge.net/ DenyHosts] package to help protect user accounts from brute-force ssh attacks.  If a user fails to login within several attempts, then the offending originating IP will be blacklisted in order to prevent additional attempts.  If the individual attempts to log in again, then they will see something similar to the following: {{{ssh_exchange_identification: Connection closed by remote host}}}.\r
\r
The blacklist expires IPs after a predetermined period of time.  Typically, most users will not be affected by the blacklisting, but if you are, you will want to contact the hcoop-sysadmin list to get your IP address removed from the list.\r
\r
= WebDAV =\r
WebDAV is accessible at https://dav.hcoop.net/.  WebDAV is useful when working on a website using systems that cannot mount an AFS share.  For details on how to setup WebDAV, take a look at http://research.cs.berkeley.edu/doc/dav/\r
\r
Note that you can only use WebDAV on directories that have {{{system:anyuser rl}}} as part of its ACL.  You'll be able to write even if {{{system:anyuser}}} does not.  See Securing Directories on this page for additional details on directory ACLs.\r
\r
= Web sites =\r
\r
== Websites with a domtool-managed domain ==\r
\r
When you publish web content, it will probably live in your home directory.  The web server will need permission to read your files, or it will return "403 Access Denied" errors.  Since your home directory is in AFS, '''normal UNIX permissions are irrelevant'''.  See AndrewFileSystem for information on how to work with AFS's '''separate''' notion of permissions.\r
\r
For instance, if you get a 403 error serving `~/public_html/otherdir/page.html`, you might run this to see what's up:\r
\r
{{{$ fs listacl ~/public_html/otherdir\r
Access list for /afs/hcoop.net/user/y/yo/you/public_html/otherdir is\r
Normal rights:\r
  system:administrators rlidwka\r
  system:anyuser l\r
  you rlidwka}}}\r
\r
Oops!  Apache only matches the "system:anyuser" principal, so it only gets the "l" (= "list") permission and can only list your directory contents.  Try this to fix it:\r
\r
{{{$ fs setacl ~/public_html/otherdir system:anyuser read\r
$ fs setacl ~/public_html system:anyuser read\r
$ fs setacl ~ system:anyuser l}}}\r
\r
The first two give full read permission on the mentioned directories. "l" permission is needed in every parent directory of a file to be able to access it, so the last line makes sure "l" is granted to system:anyuser on your home directory.\r
\r
When your web content is accessed through your own virtual host, you can also grant read access to `$USER.daemon` instead of the broader `system:anyuser`, where `$USER` is your username. This is your bizarro-world twin, which Apache runs as when serving your content.\r
\r
== Web Pages without a Domain ==\r
\r
Your {{{~/public_html}}} directory is available via HTTP through {{{http://deleuze.hcoop.net/~USER/}}}. Eventually this will change to {{{http://hcoop.net/~USER/}}}.\r
\r
Due to consequences of AFS authentication, we don't plan to allow dynamic content (CGI, PHP, etc.) via hcoop.net/~you/... on New.  If you don't have a domain hosted at HCoop, but want to serve dynamic content, then you can request an hcoop.net subdomain (example: {{{USER.hcoop.net}}}, where USER is your username) via [http://bugzilla.hcoop.net/].\r
\r
\r
= OpenAFS =\r
For now, see http://research.cs.berkeley.edu/doc/afs/ for details on how to access your AFS share from a remote computer.  Be sure to replace example domain names with hcoop.net or HCOOP.NET.\r