Admin reference

From ProgClub
Revision as of 01:11, 3 September 2011 by John (talk | contribs) (→‎Tools)
Jump to: navigation, search

__NOTITLE__ This page is a reference for ProgClub system administrators. For information about ProgClub domains, see Domains. For information about member services, see Services. See Machines for information about hosts on the ProgClub network. See Projects for current projects or check out our Forums to get in touch.

Administrative reference

If you're administering ProgClub assets, please document your actions on the wiki. See the relevant pages:

See Future machine names for the kind of stuff we're on about.

See, or update, Network administration for work that needs to be done.

Code of conduct

As a ProgClub administrator you have a lot of power. You have the capability to destroy ProgClub's files and configuration, to access all of ProgClub's databases, to pretend to be other users, and to access other users' private data. We expect you won't abuse your power. Specifically, under no circumstances should you:

  • Delete or modify in inappropriate ways ProgClub files or members' files
  • Read other users' email or private files
  • Copy data from any of ProgClub's administrative databases into your own system
  • Pretend to be another member

All of your systems administration activity should be documented, and you shouldn't be doing anything evil. If you're not sure what qualifies as evil, if you have any doubt at all, please ask.

Where are the keys?

Your administrator login on charity and your member account in LDAP will give you sudo privs on all of the ProgClub machines, both administrative and user machines. Some tools require special purpose logins, and for those you will find login details in the /home/jj5/login_* files which you can access from any of the machines.


For login information:

  • See /home/jj5/login_ldap for the LDAP login.
  • See /home/jj5/login_data for the database logins.
  • See /home/jj5/login_mail for the email login.
  • See /home/jj5/login_list for the email lists logins.


The process for documenting network administration activity is:

Note: don't use screen while administering systems, because it frags PuTTY's scroll buffer, and you need that in order to copy-and-paste your session log.

  • Update the network administration page with a note about what you did:

It's not a bad idea to link to the relevant section(s) of the admin page(s) from the network administration 'done' note, but that's not strictly necessary.

  • Let everyone know what new features are available:

Administrative and user machines

As explained on the Machines page ProgClub separates its machines into two groups: administrative machines and user machines. There is only one administrative machine, charity. There are two user machines, hope and honesty. If you're doing sysadmin work on the user machines, make sure you duplicate your work and create an identical system configuration on each machine. Both user machines should have the same configuration. And, yes, this means that you have to duplicate your documentation too. If you're doing some experimental configuration I'd suggest doing it on honesty first, and then once you've got everything figured out and stable duplicating onto hope. You can use hope first though if it suits you. Try not to let too much time pass with the systems in different configurations, generally you should do your sysadmin work on both systems immediately one after the other.

Administrator logins

The way logins work for administrators (as opposed to normal users) is that you have two logins. One login is for the administrative server (currently there is only one of these, charity), and the other login is your Kerberos/LDAP login that gets you access to the user machines. You can use different passwords if you want, but the usernames (and UIDs) will be the same. All administrators are members of the 'sudo' group on charity and in LDAP. This means that you can use your sudo privileges on either administrative machines or user machines.


Etckeeper is now installed on charity (and hope and honesty), which means the correct procedure after making edits to files in /etc is to issue:

$ sudo etckeeper commit "my reasoning here"

after you're done with your changes. There's an auto commit every day, and an autocommit whenever you apt-get install something. You can manually commit your changes as above. To see the commit log for a particular file:

$ sudo bzr log /etc/passwd

To revert an unwanted or bad change, work out which revision you want to revert to (see log above) and run:

$ sudo bzr revert --revision <commit number> <file>

For example, to restore the /etc/passwd file to the state it was in in revision 3,

$ sudo bzr revert --revision 3 /etc/passwd

To check for uncommited changes, run (From inside /etc):

$ sudo bzr status

For example:

$ sudo bzr status

If you see no output, there are no uncommited changes.

Adding a new user

Updating members database

At the moment member information is recorded in Members. A member should have a Wiki account to start with (create one for them if they haven't already created their own), then an entry in the Members page (where they are allocated a member number), then the "User info" on their user page should be filled out (leave fields as "Not disclosed" unless you have their permission to publish their details). After the Members page has been updated you will have:

  • {username}: the Unix/Kerberos username of the new member
  • {member number}: the member's User ID
  • {group}: whether the user has 'sudo' membership or not
    • there are two groups at ProgClub: 'sudo' and 'user'
      • everyone is in 'user' (gidNumber == 500)
      • administrators are in 'sudo' (gidNumber == 27)

And that's enough information to create their account as detailed below.

Kerberos administration

To create a new user in Kerberos:

  • SSH to
  • Login
  • Run kadmin addprinc:
$ sudo kadmin -p {your username} -q "addprinc {username}"
    • Note: use sudo so that the log file can be written
    • {your username} is your ProgClub username
    • {username} is the ProgClub username of the user your are adding

If the user is an administrator, add them to /etc/krb5kdc/kadm5.acl. E.g., at the end of the file,

username@PROGCLUB.ORG *

replacing 'username' as appropriate. You need to restart the Kerberos administration server after this change:

$ sudo /etc/init.d/krb5-admin-server restart

Creating home directory or administrative login

  • SSH to
  • Login

If you are creating an administrative account, run:

$ sudo adduser --uid {member number} --gid 27 {username}

If you are creating a normal user account, run:

$ sudo adduser --uid {member number} --gid 500 --disabled-password {username}

(This creates the user's home directory)

LDAP administration

To create a user in LDAP:

  • Open the LDAP administration tool
  • Login: cn=admin,dc=progclub,dc=org (/home/jj5/login_ldap for password)
  • Navigate to: ou=users
  • Click 'Create new entry here'
  • Choose 'Default'
  • Container should be: ou=users,dc=progclub,dc=org
  • ObjectClass: inetOrgPerson
  • Select the RDN attribute: Username (uid)
  • Enter 'cn', this is the Common Name, i.e. the user's full name, or their username
  • Enter 'sn', this is the Surname, i.e. the user's last name, if it's disclosed, else username
  • Enter 'displayName', i.e. the user's full name, if it's disclosed, else username
  • Enter 'Email', i.e. if they want an email account, otherwise the user's email address, if it's disclosed, else blank
  • Enter 'givenName', i.e. the user's first name, if it's disclosed, else blank
  • Enter 'Username', this is their Posix username, all lowercase
  • Click 'Create Object'
  • Review the entry and click 'Commit'
  • Scroll down to 'objectClass' and click 'add value'
  • Select 'posixAccount'
  • Enter the 'gidNumber': 27 for admin, 500 for user
  • Enter the 'homeDirectory': /home/{username}, e.g. /home/jj5
  • Enter the 'uidNumber': this is the member number allocated on the web-site in Members
  • Click 'Add ObjectClass and Attributes'
  • Review the entry and click 'Update Object'
  • Scroll down to 'objectClass' and click 'add value'
  • Select 'shadowAccount'
  • Click 'Add new ObjectClass'
  • Click 'Add new attribute'
  • Select 'loginShell'
  • Enter "/bin/bash"
  • Click 'Update Object'
  • Review changes and click 'Update Object'
  • Navigate to ou=groups
  • Select 'user'
  • Select the "Generic: Posix Group" template
  • Select the new user (all users should be selected)
  • Click 'Update Object'
  • Review changes and click 'Update Object'

If the user is an administrator:

  • Navigate to ou=groups
  • Select 'sudo'
  • Select the "Generic: Posix Group" template
  • Select the new user (all administrative users should be selected)
  • Click 'Update Object'
  • Review changes and click 'Update Object'

Email account

Login to email administration. The username is, and the password is in /home/jj5/login_mail.

  • Click Virtual List => Add Mailbox
    • Username: the member's username
    • (it will default to, which is wrong, so be careful with this)
    • Password: make a random one up and email it to the new member, they can change it themselves
    • Name: if the member gave you permission to use their name, then their name. Otherwise their username.
    • Active: checked
    • Send welcome email: checked
  • Click 'Add mailbox'.

Once you've done that, login to the user email administration facility with the member's username and the password you generated.

  • Click 'Change your forward'.
    • To: the member's non-ProgClub email address
    • Select: Deliver to the local mailbox
  • Click 'Edit alias'.

Subscribe member to ProgClub announcement

Login to announcement administration. The password is in /home/jj5/login_list.

  • Click 'Membership Management...'
  • Click 'Mass Subscription'
  • Subscribe these users now or invite them?: Subscribe
  • Send welcome messages to new subscribees?: No
  • Send notifications of new subscriptions to the list owner?: Yes
  • Enter the ProgClub email address of the new member
  • Click 'Submit Your Changes'

Tell the member about their new account

Now send an email to the member at their new email address ( letting them know the details of their new account. You should include:

Subscribe member to mailing lists

You should already have subscribed them to the announcement list. You might also like to subscribe their new ProgClub email address to any or all of the following: