III. Janitor

Contents

2. Authentication
    2.1 Login procedure
    2.2 Logout procedure
    2.3 At the command line
    2.4 Remote access

3. Menu structure of the web interface
    3.1 Users and groups
    3.2 Shortcuts
    3.3 Tools

4. Managing workgroups
    4.1 Add a workgroup
    4.2 Adding users to a workgroup
    4.3 Delete a workgroup

5. Managing users
    5.1 General information
    5.2 Adding a teacher account
    5.3 Adding a nest (grade) account
    5.4 Adding a single pupil account
    5.5 Modifying a user account
    5.6 Deleting a user account
    5.7 Adding multiple user accounts
    5.8 Adding multiple pupils via file upload
    5.9 Promoting nests (grades) manually
    5.10 Promoting nests (grades) via file upload

6. Managing CD-ROM images
    6.1 Creating .iso-files via the web interface
    6.2 Creating .iso-files via the command line
    6.3 Removing CD-ROM images

7. Advanced topics
    7.1 Tweaking Janitor via janitor.conf
    7.2 Tweaking the web interface via config.php

8. Conclusion

1. Introduction

1.1 General remarks

During the installation of ServerAtSchool at least one user account with the necessary privileges was created, see section 10.4 Adding the first user account in chapter V. Configuring all ServerAtSchool components in the ServerAtSchool Installation Guide. Because there has to be at least a single account with janitor-privileges in order to create accounts via the web interface, the first account is to be created via the command line. Subsequent user accounts can be created via either method.

Throughout this chapter the word 'group' is used in many different meanings. We try to distinguish the different meanings by using different words. The following meanings of 'group' are used.

• a Linux/Unix-group; a user account has a primary group and can also have zero or more secundairy groups
• a workgroup: a collection of users that can share documents via 'My Documents' on the server. User accounts of workgroup members belong to the corresponding Linux/Unix-group.
• a group of pupils: also known as a 'grade', a 'class' or as a 'nest'

1.2 Janitor's features

• add workgroups
• remove workgroups
• add a single teacher account
• add teacher accounts by processing a prepared file in batch
• add a single pupil account
• add pupil accounts by uploading a file (e.g. extracted from the school administration software)
• modify individual user accounts (teachers, pupils, etc.)
• promote pupils to the next grade a grade at a time
• promote pupils by uploading a file (e.g. extracted from the school administration software)
• remove user accounts
• create CD-ROM images

• Userid (can be set only once)
• Full name of the user
• The primary group a user account belongs to
• The Windows Networking password (also known as the SMB password)
• The password for access to e-mail and teleworking (also known as the shell password)
• The location of the home directory; several pre-configured options are available
• A configurable number of fields to store additional information (default 5)
• Up to 32 additional (work)groups
• A configurable number of e-mail aliases (default 5)
• Various levels of access to webmail

1.3 Layered approach

The web interface builds on the command line layer. It too can only be used by members of the group janitors. However, it is not possible to access the web interface using the password of root. This is a security measure.

1.4 Overview of this chapter

NOTICE: Note that we reduced the number of 'extra' fields in order to make the illustrations in this chapter fit on the page. Default is 5, we decreased that number to 2. See also section 7.2 Tweaking the web interface via config.php below for more information on changing this value.

Nearly all tasks that are described can be performed from either the web interface or the command line. Both methods are discussed. Note, however, that a few tasks can only be done in the web interface whereas a few other tasks can only be performed via the command line.

1.5 Additional information

(top)

2. Authentication

2.1 Login procedure

NOTICE: You can use any browser to access the web interface of Janitor; no JavaScript is required. However, it is necessary to allow cookies.

Open the relevant URL in you browser. A screen like the following appears.

janitor_login.png

Enter you username (here 'ffrint' is already entered) and password (already entered, too). Press [OK] to confirm the dialogue. Your credentials are verified and if username and password match, something like the following is displayed.

janitor_mainmenu.png

This is the main menu of the Janitor web interface. You are successfully logged in.

2.2 Logout procedure

janitor_mainmenu.png

At the upper right corner there is a link called 'logout' which enables you to end your session with Janitor. When you follow that link, the following appears.

janitor_logout.png

You are now logged out as indicated by the red message 'You have been logged out' at the top of the screen. At this point you can login again if you wish.

2.3 At the command line

praeceptor login: ffrint
Password:
Last login: Mon Sep  5 13:02:36 from c99.exemplum.serveratschool.net
[ffrint@praeceptor ffrint]$ _

At this point ffrint is sucessfully logged in on the console.

Note that you can verify your membership of the group janitors with the command id(1). This is illustrated in the snippet below.

[ffrint@praeceptor ffrint]$ id
uid=501(ffrint) gid=501)ffrint) groups=501(ffrint),94(programs),97(teleworkers),98(janitors)
[ffrint@praeceptor ffrint]$ _

Ending the session on the console can be done with the exit(1) command, as illustrated below.

[ffrint@praeceptor ffrint]$ exit
praeceptor login: _

Alternatively, you can press the keycombination [Ctrl-D] to end the session.

NOTICE: Your access to the janitor program is granted based on your membership of the janitors group. Even if you have a shell account on the server you might still be unable to use the janitor program if you are not a member of that group. Hence an ordinary teacher with shell access does not necessarily have access to the janitor program too. This is a security feature.

2.4 Remote access

[freddie@home ~]$ ssh ffrint@praeceptor.exemplum.serveratschool.net
The authenticity of host 'praeceptor.exemplum.serveratschool.net (62.59.32.61)' can't be established.
RSA key fingerprint is 24:8f:3a:85:0a:d1:25:d6:81:14:b0:22:b6:62:55:39.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'praeceptor.exemplum.serveratschool.net,62.59.32.61' (RSA) to the list of known hosts.
ffrint@praeceptor.exemplum.serveratschool.net's password:
Last login: Tue Sep  6 11:04:33 2005 on tty1
[ffrint@praeceptor ffrint]$ _

This same method can be used to login to the server from a workstation in the LAN, using the Windows-based program PUTTY.EXE. See section 11.1.3 PuTTY in chapter IV. Workstation setup. From the point of view of the server, both cases are 'remote access' (i.e. not from the console), even though accessing the server from home is more remote than accessing it via the LAN.

(top)

3. Menu structure of the web interface

janitor_mainmenu.png

At the upper left hand corner the name and the version of Janitor are displayed. The upper right hand corner shows the name of the user currently logged in.

Just below the program name and version and the user name is a gray bar. This bar is used to show a so-called breadcrumb trail, starting with the main menu, reading from left to right. Note that in submenus the various breadcrumbs are clickable, i.e. you can navigate straight to one of the previous 'crumbs' simply by clicking on the link in the gray bar.

At the right hand side of the gray bar a link called 'logout' is displayed. Following that link ends the session.

The remainder of the screen is used to display the various options of the main menu. There is a total of three options in the main menu.

• Users and groups
  This leads to the various options to manipulate user accounts and workgroups (add, delete, modify).
• Shortcuts
  This leads to various options to manipulate shortcuts ('icons') on the Desktops and in the Start Menus of the users. Note that at this time these options are not implemented in Janitor. See section 3.2 Shortcuts below.
• Tools
  This leads to various tools such as creating CD-ROM images and uploading files with pupil's data.

3.1 Users and groups

• Modify users and groups
  This option leads to the following submenu.
  • Regular users
    This option yields an overview of regular user accounts (e.g. teachers). From this overview various links can be used to edit (modify) or delete the account.
  • Nests
    This option yields an overview of all 'nests' (grades, classes). From this overview various links can be used to edit (modify) the properties of the account or delete the account. For nests there is also an option to promote the pupils of the nest (grade).
  • Other users
    This option yields an overview of other user accounts, i.e. neither regular accounts, nests or buddies. From this overview various links can be used to edit (modify) or delete the account.
  • Buddies
    This option yields an overview of buddy accounts, i.e. accounts setup for partner schools to store their backups on this server. From this overview various links can be used to edit (modify) or delete the account.
  • Workgroups
    This option yields an overview of the existing workgroups and the members of those workgroups.
  • All
    This option yields a combined overview of all of the above: regular users, nests, other users, buddies and workgroups. See below for an example.
• Add user
  This option leads to a dialogue where all properties of a new user account can be entered. By selecting the correct combinations of options, different types of accounts can be created, e.g. teachers, pupils, buddies and other user accounts.
• Add workgroup
  This option leads to a dialogue where a new workgroup can be added.

janitor_overview.png

3.2 Shortcuts

• Assign shortcuts
• Revoke shortcuts

3.3 Tools

• Edit registry
  This option is currently not implemented. Policies and registry settings are managed via a Windows workstation. See chapter VIII. Managing user profiles.
• CD-ROM images
  This option allows for creating CD-ROM images (.iso-files) using the CD-ROM player in the server.
• Upload pupils' data
  This option leads to a procedure of uploading a file with pupils' data in order to create or update all pupil accounts in one go.

(top)

4. Managing workgroups

The shared documents and files are visible via subdirectories contained within 'My Documents' (or H:\My Documents). Every member of a workgroup has access to these shared documents this way.

For example: if there exists a workgroup called 'principals', with members 'acackl' and 'adumbl', then either of the users 'acackl' or 'adumbl' has a folder called 'principals' with their own personal 'My Documents'. This is the equivalent of the subdirectory H:\My Documents\principals. No other users have access to this shared folder.

The total number of workgroups is limited to some 45,000. However, it is not possible to be a member of more than 32 groups at the same time. In practice this should be enough for a school. (If you would be a member of more than 32 workgroups, there would probably be no time left at all to do some actual work).

4.1 Add a workgroup

• Navigate to: main menu | users and groups | add group
• Enter the name of the new workgroup (here: 'staff'). Do not type the quotes.
• Click on the button [Save].

This is what is displayed on the screen while you enter the name of the workgroup.

janitor_add_workgroup1.png

This is what is shown on the screen after the new workgroup is added successfully.

janitor_add_workgroup2.png

A workgroup, say 'principals', can also be added using the command line. If you wish to add this workgroup, you should do the following. At the prompt issue the command 'janitor groupadd principals' as illustrated below.

[ffrint@praeceptor ffrint]$ janitor groupadd principals
009 success adding group 'principals' and directory '/home/userdata/home/groups/principals'
[ffrint@praeceptor ffrint]$ _

You can add workgroups either way: via the web interface or via the command line interface. You might want to add the following workgroups too: 'faculty' (for all teachers), 'healthcare' (for members of the Healthcare Committee). You also may want to add a workgroup 'jubilee'. This would be the temporary workgroup used to organise the 50th aniversary of the Exemplum Primary School.

NOTICE: The workgroups suggested here are used in other examples in the remainder of this chapter.

4.2 Adding users to a workgroup

• Navigate to: main menu | users and groups | modify users and groups | regular users
• Select the user account by clicking on the corresponding link in the column labeled 'userid'. The dialogue 'edit user' is displayed; see below.
• Click on a drop down box which has the text ----------no group selected---------- and select the relevant group
• Scroll down to the end of the page and press the [Save] button. The user is now added to the workgroup.

janitor_add_user_to_workgroup1.png

After clicking the [Save] button the following appears. Via the message 'Success modifying user: ffrint' in red at the top of the screen Janitor indicates that the properties of user 'ffrint' are changed successfully.

janitor_add_user_to_workgroup2.png

NOITICE: The number of drop down boxes in the 'edit user' dialogue is limited to the current number of workgroups of which the user is a member plus 3. If you want to add a user to more than 3 different workgroups more, you should simply repeat the procedure adding the user to at most 3 groups more at a time. The number of 'spare' drop down boxes can be configured, see section 7.2 Tweaking the web interface via config.php below.

At the command line the procedure for adding a user to one or more workgroups is a little more complicated because it is only possible to change the workgroup membership of a user by specifing all workgroups on the command line. Using the same example (adding user 'ffrint' to workgroups 'staff' and 'jubilee'), the appropriate command would look like this.

[ffrint@praeceptor ffrint]$ janitor usermod -G programs,teleworkers,janitors,principals,jubilee ffrint
[ffrint@praeceptor ffrint]$ _

Note that the switch -G is a capital letter G, not the lower case letter 'g'. Also note that the list of workgroups is comma delimited, without spaces.

4.3 Delete a workgroup

janitor_delete_workgroup1.png

At this point there is no way to delete a workgroup using the web interface; this function is not implemented yet.

However, via the command line a workgroup can easily be deleted. If you want to remove an existing workgroup (here: 'jubilee'), you should issue the following command at the prompt.

[ffrint@praeceptor ffrint]$ janitor groupdel -r jubilee
013 success removing group 'jubilee' (gid='105') and directory '/home/userdata/home/groups/jubilee'
[ffrint@praeceptor ffrint]$ _

Note that the switch -r is used here. This switch tells Janitor to also remove the shared directory from the file system, including any existing documents in that shared directory. Any shared documents elsewhere are not affected. If you do not specify this switch, the directory and any documents are retained. However, since the workgroup no longer exists there are no longer users that are allowed to access those documents.

(top)

5. Managing users

5.1 General information

5.1.1 Properties of a user account

• UserID
  Every user has to have a userid. It is used as the primary means to identify a user. The following restrictions apply.
  • a userid must consist of 1 to 16 (lowercase) letters and digits
  • a userid must begin with a letter
  • a userid must be unique within the system
  Note that Janitor allows only lowercase letters and digits in userids. Specifically punctuation like dots, dashes, slashes and the like are not acceptable, as are capital letters. Since userids must be unique some userids are not allowed because they already exist in the system (e.g. a userid 'www' or 'root'). Also note that the userid is used both for Windows Networking and e-mail and teleworking. The passwords differ, however.
• Full name
  Every user account can have an optional full name associated with it. The following restrictions apply.
  • a full name can not contain a colon ':', a comma ',' or a newline character.
  • a full name can have up to 80 characters
• (Primary) group
  Every user has to have a primary group. The rules for these groups are comparable to those for userids:
  • a group must consist of 1 to 16 (lowercase) letters and digits
  • a group must begin with a letter
  • a group must be unique within the system
• Secondary groups
  A user can be a member of 0 or more secondary groups (maximum: 32). The rules for these groups are comparable to those for userids:
  • a group must consist of 1 to 16 (lowercase) letters and digits
  • a group must begin with a letter
  • a group must be unique within the system
  Note that there are a few predefined groups within ServerAtSchool.
  • programs (94): every user that is to be able to use programs and other files from shared program directories (e.g. P:, Q: and R:) on the server should be a member of this group. If a user is not a member of this group the user is denied access to files on these shares.
  • install (95): this special group is used for the special user 'install' used with ghost for unix.
  • buddies (96): this special group is the primary group of all buddy accounts (for off-site backups of partner schools)
  • teleworkers (97): this special group allows members to access the server from home, for teleworking
  • janitors (98): this group grants special privileges for users, e.g. access to the Janitor program
• Home directory
  Every user has to have a home directory. The web interface provides 5 predefined options to choose from.
  • normal: /home/userdata/./home/users/userid
    The dot between '/home/userdata/' and '/home/users' makes that this user ends up in a chrooted environment. This is a security measure.
  • advanced user: /home/userdata/home/users/userid
    This user is not limited to the chrooted environment like a normal user. Only selected users such as local system administrators or perhaps ICT coordinators should have this type of home directory.
  • reference user/skeleton: /home/userdata/home/skeletons/userid
    This user might be used as a 'reference' user, i.e. a user account with suitable defaults that could be used when creating subsequent accounts. This feature is currently unused in Janitor.
  • buddy: /home/buddies/./home/userid
    This account ends up in another chrooted environment, possibly on a different partition and/or disk. The main purpose for this type of account is to let other schools store their backups off site, on this server.
  • other: free-format home directory
    This allows for any non-standard home directory. The full path should be specified, starting in the root directory.
  Note that documents of both 'normal' and 'advanced' users are backed up on an hourly basis (during the daytime monday - friday, default from 07:00 - 18:00) because their home directories reside under /home/userdata/home. For buddies and other users this is not the case.
• Login shell
  A login shell is necessary for users that are allowed to use teleworking. The default is that users have no login shell at all. Note that teleworking requires not only a shell (either /bin/bash or /bin/sh) and a password but also the membership of the special predefined teleworkers group.
• Password (a.k.a. E-mail and teleworking password)
  This password is used for access to e-mail (webmail) and for teleworking. A password can not contain a colon ':' or a newline character. A password is limited to a length of 16 characters.
• SMB password (a.k.a. Windows Networking password)
  Every user can have an SMB password. This password is used to logon to Windows Networking on the LAN at school. This following restrictions apply.
  • the SMB password should have 1 to 16 characters
  • the SMB password can not contain a colon ':' or a newline character
  • the SMB password NO PASSWORD is a special case; it allows users to login to the network without specifying a password at all
  Note that by specifying the special SMB password NO PASSWORD the corresponding user is granted access to Windows Networking without specifying a password. This can be a feature for the lower grades. However, the userid should still be specified.
• Extra fields
  Every user account can have additional properties in so called 'extra' fields. The number of extra fields is configurable (see section 7.2 Tweaking the web interface via config.php below). The default is 5. These fields can contain anything, allthough colons ':', comma's ',' and newline characters are not allowed. Possible use is to store a pupil's date of birth in one of the extra fields (see also section 5.4 Adding a single pupil account below).
• E-mail aliases
  A user can have 0 or more e-mail aliases. The maximum number of aliases is configurable (see section 7.2 Tweaking the web interface via config.php below). The default is 5. E-mail aliases can not contain a colon ':', a comma ',' or a newline character. However, punctuation is allowed (notably a dot). All aliases are considered to be within the school's domain name. The domain name itself should not be specified; it is appended automatically. The first e-mail alias is also used as the default for the sender (in Squirrelmail).
• Webmail access limitation
  Access to webmail can be limited. The following options exist.
  • none: the user is not allowed to acces webmail at all (equivalent to 255.255.255.255/32)
  • internal: the user is allowed to access webmail, but only from within the LAN at school (equivalent to 127.0.0.0/8,172.17.2.0/24)
  • anywhere: there are no restrictions to webmail access (equivalent to 0.0.0.0/0)
  • other: access is limited to the IP-addresses and/or networks in the specified comma-delimited list.

5.1.2 Different types of user accounts

• Regular user account
  A regular user account is an account which satisfies the following conditions.
  • the primary group has exactly the same name as the account itself
  • the numerical userid equals the numerical groupid
  • there is no other user that has this group as their primary group
• Nest (grade, class, group of pupils)
  A nest account is an account which satisfies the following conditions.
  • the primary group has exactly the same name as the account itself
  • the numerical userid equals the numerical groupid
  • there is at least 1 other user that has this group as their primary group
• Pupil account
  A pupil account is an account which satisfies the following condition.
  • the primary group of the account is the same as the primary group of a nest or a regular account.
  Note that by definition a regular user turns into a nest the moment that a (pupil) account is added to the primary group of this regular user.
• Buddy account
  A buddy account is an account which satisfies the following condition.
  • the primary group is the predefined 'buddies' group
• Other users
  Users that are not a regular user, a nest, a pupil or a buddy belong the other users.

5.1.3 Hints for user names and passwords

• first name + first letter of last name: abigaila, alicel.
• first name + number: mary1, william4.
• first letter of first name + lastname: areese, chayes, adumbledore.
• first letter of first name + first 5 letters of lastname: hparkh, bskinn.
• a non-name: p0001, p0002.

A workable solution is to construct the userids of staff using the first letter of the first name followed by a limited number of letters, say 5, of the lastname and not using the infix. This would yield 'aschur' for 'Anna Maria van Schurman'. Userids for pupils could be constructed by using the first name, optionally followed by a digit. The digits need only be used when there is actually a name clash. Of course it also possible to append a number to all pupils in order to treat them equally. By using different strategies for staff and pupils the chance that a pupil name clashes with a member of staff is minimised.

Another reason to use constructed names for staff members (which probably have teleworking privileges) is that there are many would-be crackers on the loose (also known as 'script kiddies') that try to brute-force an entry to the server using long lists of first names with obvious passwords. If the school does not have teacher accounts like 'john', 'paul' or 'george', these attempts will simply fail because those userids do not exist. If there are pupil accounts with those names the attempts will also fail because as a rule pupils do not have teleworking access to the school server. However, if you want to make it even harder for the script kiddies you could opt for always appending a number to the userids of pupils.

It is important to have good passwords for those users that will be allowed to access the school server from outside of the school (teleworking, webmail). This subject is discussed in section 2.5 Choosing passwords in chapter V. Configuring all ServerAtSchool components in the ServerAtSchool Installation Guide.

In short, a 'good' password has at least one digit (0,...,9), at least one lowercase letter (a,...,z), at least one uppercase letter (A,...,Z) and preferably at least one special character. Suitable special characters are: at-sign '@', hash '#', dollar '$', percent '%', caret '^', ampersand '&', asterisk '*', left parenthesis '(', right parenthesis ')', dash '-', underscore '_', plus '+', equals '=', left curly brace '{', right curly brace '}', opening bracket '[', closing bracket ']', semicolon ';', slash '/', dot '.' and question mark '?'. It is also a good idea to choose a password of at least 8 characters long.

NOTICE: Because of the way Janitor works you should not use a colon ':' as part of a password. The same applies to the use of a single quote ('''), a double quote ('"') and a backtick ('`').

NOTICE: There are two different passwords in ServerAtSchool. One is used for teleworking and access to e-mail (webmail). The other one is used to authenticate the user for Windows Networking. It is recommended to choose two different passwords. That way the teleworking and e-mail is still protected, even when the SMB password is compromised.

NOTICE: It is a good idea to use e-mail aliases that are different from the user accountnames. That way you can simply change to new alias when the old one is on too many spammers' lists. Once your real accountname is on a spammer's list, you can not easily stop the unwanted e-mail by changing your e-mail address because you can not change a user accountname. This is especially important with the e-mail aliases for grades (nests). It is better to use pupils.grade7@exemplum.serveratschool.net and switch to pupils.of.7th.grade@exemplum.serveratschool.net when necessary than to keep accepting spam at grade7@exemplum.serveratschool.net forever.

5.1.4 Checklist for common combinations of properties

5.2 Adding a teacher account

5.2.1 Adding a teacher account via the web interface

NOTICE: The actual output is split into two different illustrations because of layout considerations. Please use the scroll bar at the right hand side to scroll through the page.

janitor_add_teacher1.png

janitor_add_teacher2.png

Explanation:

• UserID: 'hparkh'. This is the name of the new account. This can not be changed once the account is created.
• Full name: 'Helen Parkhurst'. This is the human-readable name of the new account.
• (Primary) group: 'same as userid (default)'. By selecting this primary group to be the same as the userid, the type of the account becomes a regular user (see section 5.1.2 Different types of accounts above).
• SMB password: 'ahgiesah'. This password is used for Windows Networking access. Note that the password needs to be entered twice in order to prevent typing errors. Also note that the actual password is shown as asterisks on screen.
• Home directory: 'normal (default)'. This makes sure that this user 'hparkh' is limited to a chroot jail when using the teleworking facility. This is a security measure.
• Login shell: 'bash'. Either 'bash' or 'sh' is necessary when teleworking needs to be enabled.
• Password: 'wWITa4ye'. This password is used for teleworking access and also for access to webmail. Note that the password needs to be entered twice in order to prevent typing errors. Also note that the actual password is shown as asterisks on screen.
• Extra fields: none of the extra fields were used in this case.
• (Secondary) groups: 'programs', 'teleworkers', 'staff', 'faculty'. This teacher is member of 'programs' because she has to be able to run (educational) programs from the server. Membership of the group 'teleworkers' is necessary for working from home. Finally the membership of the workgroups 'staff' and 'faculty' allow this user to share documents and files with other members of those workgroups.
• Email aliases: 'helen.parkhurst'. This alias allows this user to receive e-mail at the address 'helen.parkhurst@exemplum.serveratschool.net'. Note that the domain name is implicit; it should not be specified here.
• Webmail access: 'anywhere'. This user is allowed to access the webmail from anywhere: within school or outside the school (e.g. at home).

After all properties are entered press the [Save] button. The following appears on the screen.

janitor_add_teacher3.png

The message in red shows that the account was created successfully.

5.2.2 Adding a teacher account via the command line

NOTICE: The command can be split over multiple lines by using the line continuation feature (the backslash '\' followed by a newline) of the shell as shown below. However, it is not necessary; you can simply type the (long) command on a single line. The command is split up in separate lines in the illustration below for layout reasons.

[ffrint@praeceptor ffrint]$ janitor useradd \
-c "Burrhus Frederic Skinner" \
-d /home/userdata/./home/users/bskinn
-G programs,teleworkers,staff,faculty \
-s /bin/bash \
-P 'coNnLV9V' \
-W 'icheiwoi' \
-E burrhus.skinner \
-I 0.0.0.0/0 \
bskinn
bskinn:505:bskinn:Burrhus Frederic Skinner:/home/userdata/./home/users/bskinn:/
bin/bash:programs,teleworkers,staff,faculty:coNnLV9V:icheiwoi:/home/userdata/ho
me/skeletons/skel:burrhus.skinner:0.0.0.0/0
[ffrint@praeceptor ffrint]$ _

Explanation:

• janitor useradd
  This is the call to the Janitor program janitor(1), asking it to perform the function useradd. (In total there are some 18 functions that can be executed this way; use janitor without parameters to get a quick overview). The remainder is a list of arguments for Janitors useradd function.
• -c "Burrhus Frederic Skinner"
  The parameter -c sets the comment field in the system's user database /usr/passwd. This field is sometimes referred to as the GECOS field. This field is used to store the name of the user in human-readable form. Note that the GECOS field is also used to store 'extra' information. See the example in section 5.4.2 Adding a single pupil account via the command line below for more specific information.
• -d /home/userdata/./home/users/bskinn
  The parameter -d defines the full path to the user's home directory. In this case the user is to be limited to a chroot jail. This is done by specifying an extra dot and a slash in the path, between 'userdata' and 'home'. If the user would not be limited to the chroot jail, the full path would have to be specified without an extra dot and a slash between 'userdata' and 'home' like this: /home/userdata/home/users/bskinn. Note that the default is to limit a new account to a chroot jail so strictly speaking this option was superfluous in this example.
• -G programs,teleworkers,staff,faculty
  The parameter -G defines the secondary groups for this user. These secondary groups must already exist before any of them are used. In this case they are all defined and can therefore be used without having to add them to the system first. By making this account a member of these groups, the following privileges are granted to the account:
  • members of the group teleworkers are allowed to access the server at school with ssh from the outside (i.e. via Internet from home, using WinSCP or PUTTY.EXE) or from the LAN (with PUTTY.EXE).
  • members of the group programs are allowed to access Windows programs and files via the Samba server.
  • members of the groups 'staff' and 'faculty' can share documents between each other.
• -s /bin/bash
  The parameter -s defines the command shell for this account. By default the 'shell' /sbin/nologin is assigned to a user account. This 'shell' simply denies access (it immediately logs out the user). This is a security measure. Only if the account has a real shell like /bin/bash the user will be able to login (remotely via ssh or at the console). Note that the account must both be a member of the group teleworkers (for access via ssh) and have a real shell.
• -P 'coNnLV9V'
  The parameter -P defines the shell password for the user account. This is the password that is used to authenticate the user for
  • access to the user's mailbox via webmail (if access to webmail is not disabled, see parameter -I below)
  • remote access to the server via ssh (if /bin/bash is specified as shell and the user is a member of the group teleworkers)
  • local access to the server at the console (keyboard/monitor of the server) if the user is a member of the group janitors
  • access to the web interface of Janitor if the user is a member of the group janitors
  Obviously this is a very important password, especially for members of the group janitors. Therefore it should be a good one. See the remarks about passwords in section 5.1.3 Hints for user names and passwords above.
• -W 'icheiwoi'
  The parameter -W defines the user's password for Windows Networking via the Samba server. This password is used to access the server from a Windows client computer. Note that a user account has two passwords. It is a good idea to make sure that both passwords are different. This keeps the -P password (sometimes called the 'difficult' password) secret, even if the -W password (sometimes called the 'easy' password or the SMB password) would be compromised.
• -E burrhus.skinner
  The parameter -E defines the user's e-mail aliases. It consists of a comma delimited list of different aliases for this user's mailbox. In this case the mailbox name is bskinn (see below, the last item in this list) and the alias defined via -E makes that mail addressed to burrhus.skinner@exemplum.serveratschool.net ends up in mailbox bskinn. Note that the first alias in the list is also used as the From-address in Squirrelmail. Also note that the domain name should not be specified here, just the bare aliases.
• -I 0.0.0.0/0
  Parameter -I defines a comma delimited list of IP-addresses from which it is allowed to access webmail (Squirrelmail). By default access to webmail is limited to the LAN, using 127.0.0.0/8,172.17.2.0/24. In the case of this user account access is unlimited; this user is allowed to access webmail from anywhere in the world. Specifying no access at all could be done via 255.255.255.255/32.
• bskinn
  This parameter specifies the name of the account. After creating the account, this name can not be changed; it can only be 'changed' by deleting and re-creating the account using another name.

5.2.3 Status quo after adding teacher accounts

janitor_add_teacher4.png

5.3 Adding a nest (grade) account

NOTICE: In these examples a nest and its pupils have no access to webmail and teleworking. Of course, pupils might be granted teleworking access and webmail access because after all, they have a normal user account even though one with miminal privileges. However, most of the time granting access is only used to enable an individual pupil to participate in school activities from home, in case of long absence due to illness (e.g. a broken leg).

Below are examples of adding a nest account via the web interface and via the command line.

5.3.1 Adding a nest (grade) account via the web interface

NOTICE: The actual output is split into two different illustrations because of layout considerations. Please use the scroll bar at the right hand side to scroll through the page.

janitor_add_nest1.png

janitor_add_nest2.png

Explanation:

• UserID: 'grade12'. This is the name of the new account. This can not be changed once the account is created. Note that special characters are not allowed here so a userid 'grade1/2' or 'grade1-2' is not possible (see notice below).
• Full name: 'Pupils grade 1 and 2'. This is the human-readable name of the new account.
• (Primary) group: 'same as userid (default)'. By selecting this primary group to be the same as the userid, the type of the account becomes a regular user (see section 5.1.2 Different types of accounts above). After adding the first pupil to the nest (see section 5.4 Adding a single pupil account below) the regular user transforms into a nest account.
• SMB password: 'NO PASSWORD. This password is used for Windows Networking access. Note that the password needs to be entered twice in order to prevent typing errors. Also note that the actual password is shown as asterisks on screen. By selecting this special password 'NO PASSWORD' (including the space, but without the quotes) this user can access the network without specifying a password. In the case of a nest (grade) this is a common trade off between no access control at all and a way too difficult password for the younger pupils.
• Home directory: 'normal (default)'. A nest should have as little privileges as possible. A 'normal' home directory is good enough because as a rule nests are not supposed to access the server via teleworking anyway.
• Login shell: 'none (default)'. Either 'bash' or 'sh' is necessary when teleworking needs to be enabled. Since nests are not allowed to work from home, no shell is necessary.
• Password: (none specified). This password would be used for teleworking access and also for access to webmail. In this case nothing is entered. This means that this nest is not able to work from home and also has no access to webmail. Note that if the password is specified, it needs to be entered twice in order to prevent typing errors. Also note that the actual password is shown as asterisks on screen.
• Extra fields: none of the extra fields were used in this case.
• (Secondary) groups: 'programs' This nest is member of 'programs' because the pupils that will be using this nest account need to be able to run (educational) programs from the server.
• Email aliases: (none) Since webmail is not enabled for this nest (no password was specified) no aliases are specified either. Note that if webmail were enabled, the domain name is implicit; it should not be specified here. A suitable alias would have been 'pupils.grade12'.
• Webmail access: 'none'. This user is not allowed to access the webmail from anywhere.

After all properties are entered press the [Save] button. The following appears on the screen.

janitor_add_nest3.png

The message in red shows that the account was created successfully.

NOTICE: This example creates a nest by the name 'grade12', pronounced as 'grade one two'. If your school happens to have a 'grade twelve' you have a name clash. A solution would be to name the nests for the youngest pupils something like 'kindergarten12', freeing the name 'grade12' for grade twelve. Alternatively your nests may already have a name the could be used as a userid, like 'ladybirds', 'fireflies', 'jaguars', etc.

5.3.2 Adding a nest (grade) account via the command line

NOTICE: The command can be split over multiple lines by using the line continuation feature (the backslash '\' followed by a newline) of the shell as shown below. However, it is not necessary; you can simply type the (long) command on a single line. The command is split up in separate lines in the illustration below for layout reasons.

[ffrint@praeceptor ffrint]$ janitor useradd \
-c "Pupils grade 3" \
-G programs \
-W 'NO PASSWORD' \
-I 255.255.255.255/32 \
grade3
grade3:507:grade3:Pupils grade3:/home/userdata/./home/users/grade3:/sbin/nologi
n:programs::NO PASSWORD:/home/userdata/home/skeletons/skel::255.255.255.255/32
[ffrint@praeceptor ffrint]$ _

Explanation:

• janitor useradd
  This is the call to the Janitor program janitor(1), asking it to perform the function useradd. (In total there are some 18 functions that can be executed this way; use janitor without parameters to get a quick overview). The remainder is a list of arguments for Janitors useradd function.
• -c "Pupils grade 3"
  The parameter -c sets the comment field in the system's user database /usr/passwd. This field is sometimes referred to as the GECOS field. This field is used to store the name of the user in human-readable form. Note that the GECOS field is also used to store 'extra' information. See the example in section 5.4.2 Adding a single pupil account via the command line below for more specific information.
• -G programs
  The parameter -G defines the secondary groups for this user in the form of a comma delimited list. These secondary groups must already exist before any of them are used. In this case there is only one: 'programs'. By making this nest account a member of the group 'programs' this account is allowed to access Windows programs and files via the Samba server.
• -W 'NO PASSWORD'
  The parameter -W defines the user's password for Windows Networking via the Samba server. This password is used to access the server from a Windows client computer. Note that a user account can have two passwords. It is a good idea to make sure that both passwords are different. This keeps the -P password (sometimes called the 'difficult' password) secret, even if the -W password (sometimes called the 'easy' password or the SMB password) would be compromised. In this particular case the account has no 'difficult' password at all. The SMB password is set to the special value 'NO PASSWORD', indicating that this user account is allowed access to Windows Networking by specifying the userid and leaving the password field empty (i.e. logon without password). Note that the special value used here ('NO PASSWORD') must be specified using quotes because this special password contains a space.
• -I 255.255.255.255/32
  Parameter -I defines a comma delimited list of IP-addresses from which it is allowed to access webmail (Squirrelmail). By default access to webmail is limited to the LAN, using 127.0.0.0/8,172.17.2.0/24. In the case of this user account access is not allowed; this user is not allowed to access webmail from anywhere in the world. Specifying unlimited access could be done via 0.0.0.0/0.
• grade3
  This parameter specifies the name of the account. After creating the account, this name can not be changed; it can only be 'changed' by deleting and re-creating the account using another name.

5.3.3 Status quo after adding nest (grade) accounts

janitor_add_nest4.png

5.4 Adding a single pupil account

Another difference with a teacher or a nest account is that a pupil generally needs even less privileges, e.g. no working from home, no teleworkers, no shell account and access to webmail limited to the school premises or even completely disabled. A pupil may not even have an SMB password, denying the pupil access to Windows Networking.

NOTICE: Of course it is possible to let pupils have their own personal accounts on the school server, maybe even allowing them to use webmail etcetera. However, most of the schools that have deployed ServerAtSchool opted for using a single account per grade. This is a pedagogical choice which adds to the sense of co-operation within a community like a school. The pupil accounts are created for the sole purpose of storing a pupil's work in such a way that this work (a 'portfolio' if you wish) can travel along with the pupil on the pupils journey from grade 1 to grade 8. The account is created as a container for files and documents rather than as a full-blown account with passwords and things. However, it certainly is possible to do so, for instance to enable an individual pupil to participate in school activities from home, in case of long absence due to illness (e.g. a broken leg).

Below are examples of adding a pupil account via the web interface and via the command line. However, it is much more practical to manage pupil accounts using the upload feature as discussed in section 5.8 Adding multiple pupils via file upload below.

5.4.1 Adding a single pupil account via the web interface

NOTICE: The actual output is split into two different illustrations because of layout considerations. Please use the scroll bar at the right hand side to scroll through the page.

janitor_add_pupil1.png

janitor_add_pupil2.png

Explanation:

• UserID: 'may. This is the name of the new account. This can not be changed once the account is created. Note that if there is already an account called 'may', this account 'may' may need to be called 'may1'. See also section 5.1.3 Hints for user names and passwords above.
• Full name: 'May Sinclair'. This is the human-readable name of the new account.
• (Primary) group: 'existing group: grade12'. By selecting this primary group the account 'may' becomes a pupil account (this is the definition of a pupil account, see section 5.1.2 Different types of user accounts above). At the same time the account 'grade12' is transformed from a regular account into a nest if this was not already the case. Note that you actually need to check the option 'existing group' (identified by the little black dot). If you do not check that option, a regular account will be created, much like the procedures described in sections 5.2 Adding a teacher account and 5.3 Adding a nest (grade) account above.
• SMB password: (nothing entered) This password is used for Windows Networking access. In this particular case no password is specified at all. This means that this pupil is denied access to Windows Networking using this account. However, the pupil can access the network via the 'grade12' nest account. This pupil's account is used as just a container of documents. Note that if a password would have been specified, the password would need to be entered twice in order to prevent typing errors. Also note that the actual password is shown as asterisks on screen. By selecting the special password 'NO PASSWORD' (including the space, but without the quotes) this user would be able to access the network without specifying a password.
• Home directory: 'normal (default)'. A pupil should have as little privileges as possible. A 'normal' home directory is good enough because as a rule pupils are not supposed to access the server via teleworking anyway.
• Login shell: 'none (default)'. Either 'bash' or 'sh' is necessary when teleworking needs to be enabled. Since pupils are not allowed to work from home, no shell is necessary.
• Password: (none specified). This password would be used for teleworking access and also for access to webmail. In this case nothing is entered. This means that this pupil is not able to work from home and also has no access to webmail. Note that if the password is specified, it needs to be entered twice in order to prevent typing errors. Also note that the actual password is shown as asterisks on screen.
• Extra fields: '00479' and '20000127'. Two fields are used in this case. The first one contains the number under which this pupil is known in the school's administration system. This is an arbitrary choice and using this field for this purpose is strictly optional. The second extra field is used to store this pupil's date of birth in the form yyyymmdd. This field, too, is chosen arbitrarily to contain a pupils date of birth. It is also strictly optional. Note that the number of extra fields is configurable, as explained in section 7.2 Tweaking the web interface via config.php below. Also note that these extra fields are in fact used when uploading pupils' data, see section 5.8 Adding multiple pupils via file upload below.
• (Secondary) groups: (none selected) This pupil is not a member of any other group besides the primary group (here: grade12), not even a member of 'programs'. This account definitely can not do very much on the server, not even run a Windows application from the server.
• Email aliases: (none) Since webmail is not enabled for this account (no password was specified) no aliases are specified either. Note that if webmail were enabled, the domain name is implicit; it should not be specified here.
• Webmail access: 'none'. This user is not allowed to access the webmail from anywhere.

After all properties are entered press the [Save] button. The following appears on the screen.

janitor_add_pupil3.png

The message in red shows that the account was created successfully.

5.4.2 Adding a single pupil account via the command line

NOTICE: The command can be split over multiple lines by using the line continuation feature (the backslash '\' followed by a newline) of the shell as shown below. However, it is not necessary; you can simply type the (long) command on a single line. The command is split up in separate lines in the illustration below for layout reasons.

[ffrint@praeceptor ffrint]$ janitor useradd \
-c "Catharina Giacomo,00439,19991015" \
-g grade3 \
-I 255.255.255.255/32 \
catharina
catharina:509:grade3:Catharina Giacomo,00439,19991015:/home/userdata/./home/user
s/catharina:/sbin/nologin::::/home/userdata/home/skeletons/skel::255.255.255.255
/32
[ffrint@praeceptor ffrint]$ _

Explanation:

• janitor useradd
  This is the call to the Janitor program janitor(1), asking it to perform the function useradd. (In total there are some 18 functions that can be executed this way; use janitor without parameters to get a quick overview). The remainder is a list of arguments for Janitors useradd function.
• -c "Catharina Giacomo,00439,19991015"
  The parameter -c sets the comment field in the system's user database /usr/passwd. This field is sometimes referred to as the GECOS field. This field is used to store the name of the user in human-readable form. However, the same field is also used to store the contents of the extra fields. This takes the form of a comma-delimited list. The first item in the list is the full name of the user, the second item is the first extra field, the third item is the second extra field, etcetera. In this case two extra fields are used. The first one stores the number '00439' under which the pupil is known in the school's administration system, the second one contains the pupil's day of birth using the format yyyymmdd. There are no restrictions to the content of the various fields except that these fields can not contains commas ',' or colons ':' because the these characters are used as delimiters. Note, however, that these extra fields are in fact used when uploading pupils' data, see section 5.8 Adding multiple pupils via file upload below.
• -g grade3
  The parameter -g defines the primary group for this user. By selecting this primary group 'grade3', the account 'catharina' becomes a pupil account (this is the definition of a pupil account, see section 5.1.2 Different types of user accounts above). At the same time the account 'grade3' is transformed from a regular account into a nest if this was not already the case. Note that the group 'grade3' should already exist. Also note that secondary groups are defined with parameter -G followed by a comma delimited list of secondary groups. However, this particular account has no secondary groups.
• -I 255.255.255.255/32
  Parameter -I defines a comma delimited list of IP-addresses from which it is allowed to access webmail (Squirrelmail). By default access to webmail is limited to the LAN, using 127.0.0.0/8,172.17.2.0/24. In the case of this user account access is not allowed; this user is not allowed to access webmail from anywhere in the world. Specifying unlimited access could be done via 0.0.0.0/0.
• catharina
  This parameter specifies the name of the account. After creating the account, this name can not be changed; it can only be 'changed' by deleting and re-creating the account using another name.

5.4.3 Status quo after adding single pupil accounts

janitor_add_pupil4.png

5.5 Modifying a user account

Below are examples of modifying a regular account (including hints for modifying nests and pupils) via the web interface and via the command line.

5.5.1 Navigating to the edit screen in the web interface

janitor_modify_user1.png

Follow the relevant link in the column 'userid', e.g. 'hparkh'. This yields a screen with the properties of the selected user account, see section 5.5.2 Changing the properties of an account via the web interface below.

If you want to change the properties of a nest or a pupil account, you should take the following steps. In Janitor, navigate to: main menu | users and groups | modify users and groups | nests. The following appears on the screen.

janitor_modify_user2.png

In this screen you can proceed to change the properties of a nest by following the link for the appropriate account in the column labeled 'userid', at the left hand side. In this example that would be either 'grade12' or 'grade3'. By following that link, you can change the properties of a nest in much the same way as you would when adding a nest account as discussed in section 5.3.1 Adding a nest (grade) account via the web interface above.

You can also proceed to change the properties of an individual pupil by following the link for the appropriate account in the second column of the screen. In this example that would be either the account of May Sinclair (follow the blue link 'may') or the account of Catharina Giacomo (follow the blue link 'catharina'). By following the link, you can change the properties of the individual pupil account in much the same way as you would when adding a pupil account as discussed in section 5.4.1 Adding a single pupil account via the web interface above.

NOTICE: In this screen there are two clickable links labeled 'grade12' and also two clickable links labeled 'grade3'. The links in the column labeled 'userid' lead to the screen where the properties of the nest can be modified. Following a link in the column labeled 'group' would take you to the screen where all pupils can be promoted to the next grade. This procedure is explained in section 5.9.2 Promoting pupils via the web interface below.

5.5.2 Changing the properties of an account via the web interface

We need to modify the properties of Helen Parkhurst's account because she is also a member of the school's Healthcare Committee and she is also the teacher for grade 3. This means that the account 'hparkh' needs to be added to the groups 'healthcare' and 'grade3' as is shown in the image below.

janitor_modify_user3.png

NOTICE: All current properties for the account are shown in the screen shown above, except the passwords. There is no way to retrieve an existing password (neither the SMB password nor the e-mail password). If a user has lost or forgotten a password, only a new one can be assigned to that user. This is a security feature.

NOTICE: The extra space for additional groups was added automatically. When creating the account initially, a total of 4 secondary groups could be added. Now, while editing the properties of the account, another three secondary groups can be added. This can be repeated until an account is a member of 32 secondary groups.

After the groups are added, all changes need to be saved. This can be done by pressing the [Save] button at the bottom of the screen.

NOTICE: If you want to discard the changes, you can simply press the [Cancel] button or navigate to another screen using the breadcrum trail in the gray bar near the top of the screen.

After pressing the [Save] button the following screen appears.

janitor_modify_user4.png

The text in red indicates that the changes were saved successfully.

NOTICE: After changing the properties of an individual pupil a slightly different screen is displayed. You can return to the list of nests by navigating in Janitor using the links in the breadcrum trail in the gray bar near the top of the screen. Simply follow the link labeled 'nests'.

5.5.3 Modifying a user account via the command line

[ffrint@praeceptor ffrint]$ janitor usershow bskinn
bskinn:505:bskinn:Burrhus Frederic Skinner:/home/userdata/./home/users/bskinn:/
bin/bash:programs,teleworkers,staff,faculty::::burrhus.skinner:0.0.0.0/0
[ffrint@praeceptor ffrint]$ janitor usermod -E burrhus.skinner,coach bskinn
[ffrint@praeceptor ffrint]$ janitor usershow bskinn
bskinn:505:bskinn:Burrhus Frederic Skinner:/home/userdata/./home/users/bskinn:/
bin/bash:programs,teleworkers,staff,faculty::::burrhus.skinner,coach:0.0.0.0/0
[ffrint@praeceptor ffrint]$ _

Explanation:

• janitor usershow bskinn
  The first command shows all relevant properties of the existing account 'bskinn', including the list of e-mail aliases. In this case, this comma delimited list consists of a single alias: 'burrhus.skinner'.
• janitor usermod -E burrhus.skinner,coach bskinn
  This command uses the -E switch to change the complete list of e-mail aliases. Note that existing aliases need to be specified too in order to preserve them. This command works in such a way that the existing list is replaced by the new list. You can not 'add' an alias.
• janitor usershow bskinn
  The second command shows the new properties of the account. This is used to verify that everything went OK.

NOTICE: It is important to remember that the 'usermod' command in janitor(1) replaces properties rather than extends the existing ones. This is especially important when adding a user to a new (secondary) group using the -G switch: you should specify all the existing secondary groups for the account and add the new group to that list.

NOTICE: The human readable name of the account is stored in the comment field in /etc/passwd. This is sometimes referred to as the GECOS field. ServerAtSchool uses this field not only to store the full name of the user, but also for the so-called 'extra' fields. Therefore changing or adding an extra field (using the -c switch) involves specifying the existing contents of the other extra fields and the full name, too. See also section 5.4.2 Adding a single pupil account via the command line above for an example of the -c switch.

5.6 Deleting a user account

5.6.1 Deleting a regular user account

janitor_delete_user1.png

Follow the link in the rightmost column (labeled 'delete') for the account you wish to delete. e.g. for Helen Parkhurst follow the link in the last line. A confirmation dialogue appears.

janitor_delete_user2.png

At this point you can confirm the deletion of the user account by pressing the [Delete] button. After pressing that button the following appears on screen.

janitor_delete_user3.png

The message in red confirms that the user account is in fact removed from the system.

It is also possible to remove accounts using the command line. If you want to delete an acocunt that way, you have to be logged in your shell account on the server. You should issue the following command to delete a user account (in this example the user account 'bskinn'). Note that your input is emphasised in the illustration below.

[ffrint@praeceptor ffrint]$ janitor userdel -r bskinn
047 success removing user 'bskinn' (uid=505)
046 success removing group 'bskinn' (gid='505')
[ffrint@praeceptor ffrint]$ _

After issuing this command the regular account 'bskinn' is removed from the system in two distinct steps. First the user account itself is removed, see message 047 in the example. After that the user accounts primary group is deleted, see message 046. The switch -r makes sure that all data in this account's home directory and below is removed. If you do not specify this -r switch, all files belonging to this user are left as-is; the home directory is left intact.

NOTICE: The -r switch only deletes the directory tree starting at the user's home directory. Any shared files, e.g. files in the workgroup 'staff' or 'faculty' are retained whether -r was specified or not.

NOTICE: Deleting a regular user account via the web interface always implies the -r switch.

NOTICE: Messages from Janitor all have a number like '046' and '047'. This makes it easier to parse the output from Janitor with another program even if the messages themselves would have been translated into another language. A complete list of message can be found in /etc/janitor/janitor.msg. Further discussion of this mechanism is beyond the scope of this manual.

5.6.2 Deleting a pupil account

If you want to delete a pupil account using the web interface you should take the following steps. In Janitor, navigate to: main menu | users and groups | modify users and groups | nests. The following appears on the screen.

janitor_delete_pupil1.png

This is an overview of all nests (grades) with pupil accounts. Before you can delete an individual pupil account, you have to 'zoom in' in the list of pupils in a particular grade. You can do so by following the link in the second column of the nest (grade) of interest. In this example, follow the link labeled 'grade12' in the column 'group'. The following screen appears.

NOTICE: If you follow the link in the left-most column you end up in the screen where you can modify the properties of the nest as explained in section 5.5.1 Navigating to the edit screen in the web interface above.

janitor_delete_pupil2.png

This screen presents to you an overview of all pupils in the selected nest (grade), here 'grade12'.

NOTICE: The main purpose of this screen is to move pupil accounts to another nest (grade), a nest at a time. This is discussed in section 5.9 Promoting nests (grades) manually below. However, the same screen is also used to delete individual pupil accounts.

The list of all pupils in grade12 is very short in this case; there is only one pupil: 'May Sinclair'. If you want to delete this pupil account, including all personal files and documents that belong to this user, you should follow the link labeled 'delete' in the rightmost column. The following screen appears.

janitor_delete_pupil3.png

At this point you can confirm the deletion of the user account by pressing the [Delete] button. After pressing that button the following appears on screen.

janitor_delete_pupil4.png

The message in red confirms that the user account is in fact removed from the system.

Note that by removing the last pupil, the account 'grade12' is now an empty nest. If necessary, it can now be deleted, see section 5.6.3 Deleting a nest (grade) account below. Also, because there are no pupils in 'grade12' anymore, the nest account is transformed back into a regular account.

It is also possible to remove accounts using the command line. If you want to delete an acocunt that way, you have to be logged in your shell account on the server. You should issue the following command to delete a user account (in this example the user account 'catharina'). Note that your input is emphasised in the illustration below.

[ffrint@praeceptor ffrint]$ janitor userdel -r catharina
047 success removing user 'catharina' (uid=509)
[ffrint@praeceptor ffrint]$ _

Note that only the bare account 'catharina' is deleted (message 047 in the illustration). The primary group of the account, 'grade3' is not deleted automatically. This is done this way because there is at least 1 other account that has the group 'grade3' as the primary group. This is the account 'grade3' itself. Therefore the group 'grade3' can not be deleted at this time.

The switch -r makes sure that all data in this account's home directory and below is removed. If you do not specify this -r switch, all files belonging to this user are left as-is; the home directory is left intact.

NOTICE: The -r switch only deletes the directory tree starting at the user's home directory. Any shared files are retained whether -r was specified or not.

NOTICE: Deleting an account via the web interface always implies the -r switch.

NOTICE: Because 'catharina' was the last pupil of 'grade3' the account 'grade3' is now an empty nest. Therefore it is transformed back into a regular account. If necessary, it can now be deleted.

5.6.3 Deleting a nest (grade) account

After you have removed all pupils from the nest, the nest account is transformed back into a regular account. If you now want to delete the empty nest account, you should take the following steps. In Janitor, navigate to: main menu | users and groups | modify users and groups | all. The following appears on the screen.

janitor_delete_nest1.png

NOTICE: You could have navigated to: main menu | users and groups | modify users and groups | regular users. However, by selecting 'all', you get a clean overview of all users and groups, not just regular users.

Follow the link in the rightmost column (labeled 'delete') for the account you wish to delete. e.g. for 'Pupils grade 1 and 2' follow the link in the second line. A confirmation dialogue appears.

janitor_delete_nest2.png

At this point you can confirm the deletion of the user account by pressing the [Delete] button. After pressing that button the following appears on screen.

janitor_delete_nest3.png

The message in red confirms that the user account is in fact removed from the system.

It is also possible to remove accounts using the command line. If you want to delete an account that way, you have to be logged in your shell account on the server. You should issue the following command to delete a user account (in this example the account 'grade3'). Note that your input is emphasised in the illustration below.

[ffrint@praeceptor ffrint]$ janitor userdel -r grade3
047 success removing user 'grade3' (uid=507)
046 success removing group 'grade3' (gid='507')
[ffrint@praeceptor ffrint]$ _

After issuing this command the regular account 'grade3' is removed from the system in two distinct steps. First the user account itself is removed, see message 047 in the example. After that the user accounts primary group is deleted, see message 046. The switch -r makes sure that all data in this account's home directory and below is removed. If you do not specify this -r switch, all files belonging to this user are left as-is; the home directory is left intact.

NOTICE: The -r switch only deletes the directory tree starting at the user's home directory. Any shared files are retained whether -r was specified or not.

NOTICE: Deleting a user account via the web interface always implies the -r switch.

5.7 Adding multiple user accounts

This section illustrates the possibilities of batched creation of user accounts. Section 5.7.1 File format for batch processing discusses the rules which the batch file has to obey for correct processing. Section 5.7.2 Preparing a batch file for the staff members shows how a batch file could be created. Finally section 5.7.3 Processing the batch file shows how a prepared batch is processed using the command line.

The main purpose of this feature of Janitor is to mass-create the accounts for the members of the school's staff. As a rule this is a one-time operation. Subsequent addtitions of staff accounts can easily be done manually, using the procedures discussed in section 5.2 Adding a teacher account above. Of course this assumes a reasonable (i.e. not too many) number of new accounts every (school)year.

Adding pupil accounts is a different matter because a school usually has many more pupils than teachers. This is the reason for a special procedure for adding pupil accounts in bulk, see section 5.8 Adding multiple pupils via file upload below.

The example in this section focusses on adding accounts for all members of the staff of the Exemplum Primary School. The example starts at the same point as the beginning of section 5. Managing users as shown in the illustration below.

NOTICE: Refer to section 2. The Exemplum Primary School in chapter II. ServerAtSchool User Manual Overview for details about the school population.

janitor_status_quo.png

As you can see, there is only a single regular account (Freddie Frinton). No nests (grades) exist yet. However, all necessary workgroups such as 'faculty', 'healthcare' and 'staff' are already created (see section 4.1 Add a workgroup above).

5.7.1 File format for batch processing

The format of this string is as follows:

userid:uid:pgroup:gecos:home:shell:sgroups:pwd:smbpwd:skel:aliases:ips

Explanation:

• userid: the name of the account (max. 16 letters and digits)
• uid: numerical user id
• pgroup: the name of the primary group (max. 16 letters and digits)
• gecos: a comma delimited list of additional information:
  • The first subfield is the account's 'Full name'
  • The second subfield holds the contents of the field 'Extra 1'
  • The third subfield holds the contents of the field 'Extra 2', etc.
• home: full path to user's home directory
• shell: full path to the command shell for this account
• sgroups: comma delimited list of secondary groups (max. 16 letters and digits each)
• pwd: shell password, a.k.a. the 'difficult' password
• smbpwd: smb password, also known as the Windows Networking or the 'easy' password
• skel: skeleton directory
• aliases: comma delimited list of e-mail aliases
  • The first subfield is the first e-mail alias and also the sender address in Squirrelmail
  • The second subfield is the second e-mail alias, etc.
• ips: comma delimited list of allowable IP-addresses for web mail access (CIDR format)

If these fields are non-empty in the batch file, they should conform to the rules as specified in section 5.1.1 Properties of a user account, e.g. a userid must consist of 1 to 16 lowercase letters and digits, starting with a letter, etcetera. However, if the fields are left empty, the following default values apply.

• userid: there is no default, the userid must be specified.
• uid: the next available number in the system
• pgroup: the same as the userid field
• gecos: empty string (no full name, and no extra fields)
• home: /home/userdata/./home/users/userid
• shell: /sbin/nologin
• sgroups: empty (no secondary groups)
• pwd: none
• smbpwd: none
• skel: /home/userdata/home/skeletons/skel
• aliases: empty
• ips: 127.0.0.0/8,172.17.2.0/24 (webmail access limited to the LAN)

The most basic input file that could be used would consist of a userid followed by 11 colons per account, like the three shown below.

acackl:::::::::::
adumbl:::::::::::
hgronb:::::::::::

5.7.2 Preparing a batch file for the staff members

acackl:::Amelia Cackle::/bin/bash:programs,teleworkers,staff,principals,janitors:gN8OKrK1:waavaegh::amelia.cackle:0.0.0.0/0
adumbl:::Albus Dumbledore::/bin/bash:programs,teleworkers,staff,principals:jrNgtGyP:uaxefiko::albus.dumbledore:0.0.0.0/0
hgronb:::Honorine Hermelin Gronbech::/bin/bash:programs,teleworkers,staff,faculty:UAPjJ6bn:iekufaid::honorine.gronbech:0.0.0.0/0
aschur:::Anna Maria van Schurman::/bin/bash:programs,teleworkers,staff,faculty:PoVRLubL:metheese::annamaria.vanschurman:0.0.0.0/0
mastel:::Mary Astell::/bin/bash:programs,teleworkers,staff,faculty:H6JmE006:eehohdea::mary.astell:0.0.0.0/0
wblade:::Wilhelmina Bladergroen::/bin/bash:programs,teleworkers,staff,faculty:jpvnJIgb:eezuveek::wilhelmina.bladergroen:0.0.0.0/0
mmonte:::Maria Montessori::/bin/bash:programs,teleworkers,staff,faculty,healthcare:k6aVkNSu:jiesooli::maria.montessori:0.0.0.0/0
hparkh:::Helen Parkhurst::/bin/bash:programs,teleworkers,staff,faculty,healthcare:wWITa4ye:ahgiesah::helen.parkhurst:0.0.0.0/0
odecro:::Ovide Decroly::/bin/bash:programs,teleworkers,staff,faculty:j3m1odN5:ohngiegu::ovide.decroly:0.0.0.0/0
lvygot:::Lev Vygotsky::/bin/bash:programs,teleworkers,staff,faculty,healthcare:3XtMaKjX:hoofahni::lev.vygotsky:0.0.0.0/0
ppeter:::Peter Petersen::/bin/bash:programs,teleworkers,staff,faculty:dYa34K7Z:eeteeyoo::peter.petersen:0.0.0.0/0
cfrein:::Celestin Freinet::/bin/bash:programs,teleworkers,staff,faculty:1jvGRsa5:aeghicae::celestin.freinet:0.0.0.0/0
bskinn:::Burrhus Frederic Skinner::/bin/bash:programs,teleworkers,staff,faculty:coNnLV9V:icheiwoi::burrhus.skinner:0.0.0.0/0
pfreir:::Paolo Freire::/bin/bash:programs,teleworkers,staff,faculty:2jgtjRBs:iewohsho::paolo.freire:0.0.0.0/0
iillic:::Ivan Illich::/bin/bash:programs,teleworkers,staff,faculty:h1x1ahto:dusuvagi::ivan.illich:0.0.0.0/0

Explanation:

• userid: all accounts have a userid constructed from the first letter of the first name followed by at most 5 letters of the last name, not using the infix (see 'aschur').
• uid: default for all accounts; the system will assign the next available number
• pgroup: default for all accounts: the same as the userid field
• gecos: the full name of the staff member, but no 'extra' fields are used
• home: default for all accounts: /home/userdata/./home/users/userid
• shell: /bin/bash for all accounts because all staff members are allowed to access the school server from home (for teleworking). This requires a real shell.
• sgroups: constructed for each staff member individually. All accounts are member of 'programs', 'teleworkers' and 'staff', all teachers are member of 'faculty'. There are also a few 'special cases' such as accounts 'acackl' and 'adumbl'.
• pwd: a personal password with uppercase letters, lowercase letters and digits
• smbpwd: a personal password with only lowercase letters
• skel: default for all accounts: /home/userdata/home/skeletons/skel
• aliases: a single alias constructed from firstname followed by a dot followed by infix and lastname (see 'aschur' and 'hgronb')
• ips: 0.0.0.0/0 which implies unlimited access to webmail

There are no real 'tricks' to generate a file like this example in 'staff.in'; it is unfortunately a matter of sitting down and using an editor to type in the information. However, using the pwgen(1) tool may help you to generate more or less complex passwords.

NOTICE: If you have created the batch file, be sure to store it in a safe place. After all, it contains the passwords of all staff members in an easy readable form. It would be unwise to leave this file lying around. The least thing you should do is to use chmod(1) to limit the permissions to 0600 or even 0400, i.e. only accessible by you, the owner of the file. You may even want to consider deleting the file after you have processed it (but see the notice below).

NOTICE: If you have created a batch input file 'staff.in' you might want to keep it at least for a little while in order to be able to efficiently prepare the workstation lateron. See section 5. Inaugurating new user accounts in chapter VIII. Managing user profiles where you login once for every user, using the user's password.

5.7.3 Processing the batch file

[ffrint@praeceptor ffrint]$ janitor useradd -b staff.in
acackl:504:acackl:Amelia Cackle:/home/userdata/./home/users/acackl:/bin/bash:pro
grams,teleworkers,staff,principals,janitors:gN8OKrK1:waavaegh:/home/userdata/hom
e/skeletons/skel:amelia.cackle:0.0.0.0/0
adumbl:505:adumbl:Albus Dumbledore:/home/userdata/./home/users/adumbl:/bin/bash:
programs,teleworkers,staff,principals:jrNgtGyP:uaxefiko:/home/userdata/home/skel
etons/skel:albus.dumbledore:0.0.0.0/0
hgronb:506:hgronb:Honorine Hermelin Gronbech:/home/userdata/./home/users/hgronb:
/bin/bash:programs,teleworkers,staff,faculty:UAPjJ6bn:iekufaid:/home/userdata/ho
me/skeletons/skel:honorine.gronbech:0.0.0.0/0
aschur:507:aschur:Anna Maria van Schurman:/home/userdata/./home/users/aschur:/bi
n/bash:programs,teleworkers,staff,faculty:PoVRLubL:metheese:/home/userdata/home/
skeletons/skel:annamaria.vanschurman:0.0.0.0/0
mastel:508:mastel:Mary Astell:/home/userdata/./home/users/mastel:/bin/bash:progr
ams,teleworkers,staff,faculty:H6JmE006:eehohdea:/home/userdata/home/skeletons/sk
el:mary.astell:0.0.0.0/0
wblade:509:wblade:Wilhelmina Bladergroen:/home/userdata/./home/users/wblade:/bin
/bash:programs,teleworkers,staff,faculty:jpvnJIgb:eezuveek:/home/userdata/home/s
keletons/skel:wilhelmina.bladergroen:0.0.0.0/0
mmonte:510:mmonte:Maria Montessori:/home/userdata/./home/users/mmonte:/bin/bash:
programs,teleworkers,staff,faculty,healthcare:k6aVkNSu:jiesooli:/home/userdata/h
ome/skeletons/skel:maria.montessori:0.0.0.0/0
hparkh:511:hparkh:Helen Parkhurst:/home/userdata/./home/users/hparkh:/bin/bash:p
rograms,teleworkers,staff,faculty,healthcare:wWITa4ye:ahgiesah:/home/userdata/ho
me/skeletons/skel:helen.parkhurst:0.0.0.0/0
odecro:512:odecro:Ovide Decroly:/home/userdata/./home/users/odecro:/bin/bash:pro
grams,teleworkers,staff,faculty:j3m1odN5:ohngiegu:/home/userdata/home/skeletons/
skel:ovide.decroly:0.0.0.0/0
lvygot:513:lvygot:Lev Vygotsky:/home/userdata/./home/users/lvygot:/bin/bash:prog
rams,teleworkers,staff,faculty,healthcare:3XtMaKjX:hoofahni:/home/userdata/home/
skeletons/skel:lev.vygotsky:0.0.0.0/0
ppeter:514:ppeter:Peter Petersen:/home/userdata/./home/users/ppeter:/bin/bash:pr
ograms,teleworkers,staff,faculty:dYa34K7Z:eeteeyoo:/home/userdata/home/skeletons
/skel:peter.petersen:0.0.0.0/0
cfrein:515:cfrein:Celestin Freinet:/home/userdata/./home/users/cfrein:/bin/bash:
programs,teleworkers,staff,faculty:1jvGRsa5:aeghicae:/home/userdata/home/skeleto
ns/skel:celestin.freinet:0.0.0.0/0
bskinn:516:bskinn:Burrhus Frederic Skinner:/home/userdata/./home/users/bskinn:/b
in/bash:programs,teleworkers,staff,faculty:coNnLV9V:icheiwoi:/home/userdata/home
/skeletons/skel:burrhus.skinner:0.0.0.0/0
pfreir:517:pfreir:Paolo Freire:/home/userdata/./home/users/pfreir:/bin/bash:prog
rams,teleworkers,staff,faculty:2jgtjRBs:iewohsho:/home/userdata/home/skeletons/s
kel:paolo.freire:0.0.0.0/0
iillic:518:iillic:Ivan Illich:/home/userdata/./home/users/iillic:/bin/bash:progr
ams,teleworkers,staff,faculty:h1x1ahto:dusuvagi:/home/userdata/home/skeletons/sk
el:ivan.illich:0.0.0.0/0
029 succes adding users from file 'staff.in'
[ffrint@praeceptor ffrint]$ _

The janitor-command can take a parameter -b followed by a file name, which tells janitor to use the contents of the specified file as input. Processing this batch file takes only a short while (minutes or even tens of seconds if you have fast hardware).

You can now use the web interface to see the results of your actions. If you use Janitor, and navigate to: main menu | users and groups | modify users and groups | regular users, you see the following.

janitor_add_user_batch1.png

If you navigate to: main menu | users and groups | modify users and groups | workgroups, you see the following.

janitor_add_user_batch2.png

Chances are that you forgot something in the batch file. There is no need to worry. You can simply edit a single user using the procedure described in section 5.5 Modifying a user account. For instance: 'acackl' is supposed to be a Janitor, but in that case she should not be a normal home directory (which will limit the account to a chrooted jail) but an advanced user with full access to the server's file system.

At this point it is not yet possible to add the teachers to their respective nests (grades) because these nests do not exist yet. However, it would have been possible to add the creation of these accounts before the creation of the accounts of staff members. Here we chose to assign the teachers to their nests manually after creating the pupil accounts via file upload (see the next section).

NOTICE: If you have processed staff.in and then discover a mistake, you can not correct the input file and rerun the batch processing command. This is due to the fact that all user accounts from the first run now exist. You can not add a user account with a userid that already exists. You have the option to adjust the individual accounts as discussed in section 5.5 Modifying a user account. If you really made huge mistakes, you may want to consider to remove the accounts and then restart with the newer and better version of staff.in. Deleting a number of accounts could be done one by one (see section 5.6.1 Deleting a regular user account) or using a command line like this: janitor userdel -r acackl adumbl hgronb aschur ... pfreir iillic. Once all the accounts are removed you can start over with a new batch file.

5.8 Adding multiple pupils via file upload

• Pupil's data needs to be extracted from the school administration software. The format of the extracted data can be either a fixed record length file or a comma delimited file.
• The extracted file is then uploaded using the web interface.
• After uploading the file, the data is adjusted where necessary and when all name clashes are resolved a batch file is generated
• Finally the generated batch file is processed on the command line.

5.8.1 Attributes of pupil's data

Janitor is capable of processing two different file formats for upload of pupil's data: fixed record length and comma delimited. Definitions of both file formats can be customised on the fly by specifying the details in the upload dialogue (see section 5.8.2 Uploading the file with pupil's data below). The default values for the file upload can also be configured. This is done via a configuration file as explained in section 7.2 Tweaking the web interface via config.php below.

The following attributes are used to construct pupil accounts and nests (grades).

• unique key
  This attribute uniquely identifies the pupil in the school administration system. This field is used to update existing pupil accounts when subsequent uploads are processed (see section 5.10 Promoting nests (grades) via file upload below. Eventually, the unique key is stored in the second subfield of the GECOS field of the pupil account, in the file /etc/passwd. (This equates to the field 'Extra 1' in the web interface)
• first name
  The first name is used to construct the full name of the pupil by combining the first name with the infix (if any) and the last name. The first name is also used to construct the userid of the pupil's account.
• infix
  The infix is used to construct the pupil's full name by combining it with the first name and the last name.
• last name
  The last name is used to construct the pupil's full name by combining it with the first name and the infix (if any).
• grade
  The pupil's grades are used to construct a list of different grades that exist in the school community. These grades all get a (constructed) name which eventually leads to a nest (grade) account. The pupil's grade is also used to link the pupil account to this nest (grade) account via the pupil's primary group.
• date of birth
  The date of birth is stored in the third subfield of the GECOS field much the same as the unique identifier. (This equates to the field 'Extra 2' in the web interface). The date of birth is used to 'recognise' existing accounts when existing pupil accounts updated via subsequent uploads. (See section 5.10 Promoting nests (grades) via file upload below for more information on the update procedure).

NOTICE: Because some standard file formats only use the last two digits of the year, the correct century is inferred by using the current date, i.e. the date on which the upload is processed. That is, if the value of the two-digit year is greater than the current year, the century is assumed to be the 20th century and thus 1900 is added to the two-digit year. If the value of the specified two-digit year is less or equal to the current (two-digit) year, the century is assumed to be the 21st century and therefore 2000 is added. This construction is based on the fact that it is highly unlikely that a pupil's date of birth will be in the future. This means that in 2005 the years '06' to '99' will be interpreted as '1906' to '1999' and years '00' to '05' will be interpreted as '2000' to '2005'. Note that all years are converted to 4-digit years internally.

NOTICE: The default file format is patterned after the so-called 'EDEX' file format (EDucational EXchange). This fixed record length format is used by many publishers of school administration software in The Netherlands to exchange pupil's data. This explains the references to the 'edex.php' module you may encounter.

NOTICE: The pupil data should not contain comma's ',' or colons ':' because these characters are used as delimiters. This applies to both the Fixed Record Length and the Comma Separated Values.

5.8.2 Uploading the file with pupil's data

janitor_upload_pupils1.png

Explanation:

• Fileformat: select 1 of the 4 file formats. Default value is 'Fixed Record Length'. Other options are 'CSV (dateformat=YY/MM/DD)', 'CSV (dateformat=MM/DD/YY)' and 'CSV (dateformat=DD/MM/YY)'.
• Filename: use the [Browse] button to select the file containing the data to upload (already done in the illustration).
• Field definitions: two sets of field definitions can be defined. Your choice for 'Fileformat' determines which definition is used.
  • Fixed start: this defines the starting position of a field (1 means the first position of the line)
  • Fixed length: this defines the length of a particular field.
  • CSV index: this defines the number of the field within the comma delimited line (1 means the first field)
• Unique key: the unique identifier for the pupil
• First name: the first name of the pupil
• Infix: the infix of the pupil's name (if any)
• Last name: the last name of the pupil
• Grade: the pupils grade (class)
• Birthday: pupil's birthday. The format should match the choice made in 'Fileformat' above. This field is used only for comma delimited upload files.
• Birthday (year, month, day): pupil's birthday split into individual components. This is only relevant for fixed record length upload files.

NOTICE: You can change the defaults in this upload screen, see section 7.2 Tweaking the web interface via config.php below. The distribution defaults correspond the the EDEX format as mentioned before.

5.8.3 Preparing the pupil's data

janitor_upload_pupils2.png

This screen consists of two (long) tables. The first table is a list of nests-to-be. This table is labeled 'groups'. The second table contains a list of all pupil-accounts-to-be. This table is labeled 'users'.

The first table ('groups') has three columns.

• ID: This is the (unique) identifier of a grade. It is used to link pupils to nests (grades).
• Groupname: This is the suggested name of the nest (grade). Note that by default the name of the grade consists of the word 'grade' followed by the ID in the previous column. This field can be edited so you can change the default name into something else ('ladybirds' instead of 'grade1', 'fireflies' instead of 'grade3', etc.).
• Comments: This is the place where Janitor shows comments when something is wrong with this particular grade.

The second table ('users') has four columns.

• ID: This column shows the unique identifier of a pupil, e.g. '00445' for pupil 'Abigail Adams'. It also shows the grade of this pupil between parentheses, e.g. '(6)'. Note that this links the pupil to the nest (grade) in the previous table.
• UserID: This is the suggested userid that will be used for this pupil. Note that this userid is based on the first name of the pupil. This field can be edited.
• Full Name: This is the suggested Full name of the pupil. It is constructed using first name, infix and last name from the uploaded file. This field can be edited.
• Comments: This is the place where Janitor shows comments when something is wrong with this particular pupil account.

The message in red ('More editing required') at the top of the screen indicates that there are some issues that need to be resolved before the accounts can be created. An example is the suggested userid 'andre marie'. This userid contains a space which is not acceptable in a userid. Therefore the record is shown with a different background colour. The following colour coding is used:

• Blue: the information in the record (pupil or nest) looks acceptable; this proposed (new) account does not conflict with existing accounts and obeys all the rules for account names etc.
• Yellow: the information in the record (pupil or nest) looks acceptable and furthermore because an account of this name already exists, the existing account will be updated rather than duplicated under another name.
• Orange: this account (pupil or nest) requires special attention. It could be a nest that combines two different grades (e.g. grade 1 and grade 2 in the same nest 'grade12'). It could also be an indication of a pupil account that already exists but under another name.
• Red: the information for this account is not acceptable: either another (and completely different) account with the same name already exists, the suggested name is not acceptable due to embedded punctuation (dots, dashes, etc.) or spaces or there are other anomalies with this proposed new account.

At the bottom of the page there are two buttons: [Recalculate] and [Cancel] as shown in the illustration below.

janitor_upload_pupils3.png

After editing the appropriate fields ('Groupname', 'UserID' or 'Full Name') you can press the [Recalculate] button. This instructs Janitor to re-evaluate the collection of new accounts. Any conflicts that yield a 'red' background must be resolved. Issues in an 'orange' background are mere warnings but are acceptable as far as Janitor is concerned.

A solution for the name clashes might be to add a digit to the younger pupils with the same name, e.g. Mary Wollenstonecraft in grade 6 gets to get the account 'mary' whereas Mary Fields in grade 1 gets the account 'mary1'.

Another solution might be to append the first letter of the last name to the first name, e.g. William Morris in grade 7 gets 'williamm' (with two M's) and William Blake (also in grade 7) gets 'williamb'. However, this does not solve the problem completely, because by the same token William Bradford in grade 3 would also have a claim on the account name 'williamb'. There is no ultimate answer for these problems, you have to develop your own strategy here.

NOTICE: The example with the Williams illustrates that the account names should not just be unique within a grade (the two Williams in grade 7) but throughout the complete school population. There is only a single list of accounts on the server and all accounts have to be unique. Furthermore, if the userid's would only have to be unique within a grade, you run into problems as soon as a 'william' in grade 7 has to do the grade again and new 'william' from last years grade 6 now is a pupil in grade 7 too.

NOTICE: It is important to construct the account names very carefully because the userid is associated with the pupils throughout their school careers.

NOTICE: It may be hard for Maria Montessori, the teacher in grade 7, to link the names 'william1' and 'william3' to the correct William. The easiest way to learn who is who is probaly to ask the local systems administrator (Freddie Frinton) or the ICT coordinator (Amelia Cackle). They can easily retrieve an overview of all nests where the userids are shown together with the full names.

You can use the [Recalculate] button repeatedly while working your way through the lists, resolving all pending issues. In the two illustrations below all 'red' issues are resolved but an 'orange' issue is introduced. The pupils of grade 1 and grade 2 are combined into a single nest (grade). This is also indicated via the comment 'Name is used more than once'. However, despite the 'orange' issues Janitor still considers the data acceptable, as indicated by the remark 'Everything looks OK' at the top of the screen.

janitor_upload_pupils4.png

janitor_upload_pupils5.png

Note that there now is a third button [Generate] at the bottom of the screen. Pressing this button generates a batch file and a script that has to be processed at the command line.

NOTICE: The whole procedure, from uploading a file upto the moment that you can press the [Generate] button has to take place in a single session. There is no way to save your changes and continue lateron.

5.8.4 Generating the batch file for creating pupil accounts

janitor_upload_pupils6.png

Janitor's message in red now reads: 'Everything is OK: results written in file /var/tmp/file20050831231325'. The remainder of the screen shows the contents of two files and an [OK] button at the end. The first file is a shell script called '/var/tmp/file20050831231325.sh'. The contents is a single instruction, namely the janitor useradd command with the switch -b followed by the name of the second file.

The second file is called '/var/tmp/file20050831231325.in'. This is a batch input file which conforms the the format discussed earlier (in section 5.7.1 File format for batch processing). The contents of this file corresponds to the data of all nests and pupils which was prepared in the previous sections.

The shell script has to be executed at the command line, e.g. by the local systems administrator (Freddie Frinton). It is necessary to do this using the root account or at least with root privileges because the files created are not readable by members of the group 'janitors'. Making the procedure of creating the pupil accounts a two-step process is a security measure. It gives the local systems administrator an opportunity to examine the batch file before it is processed.

After pressing the [OK] button you return to Janitor's main menu.

NOTICE: You can see in the illustration that the nest (grade) accounts all have an SMB password 'NO PASSWORD'. This is a special password which grants the nest accounts access to Windows Networking without specifying a password. See also sections 5.1.1 Properties of a user account and 5.3 Adding a nest (grade) account for more information on the SMB password.

NOTICE: The SMB password (here 'NO PASSWORD' for the nests) is generated based on the configuration of the web interface as discussed in section 7.2 Tweaking the web interface via config.php below. There are three options for automatically generating a password: none at all, 'NO PASSWORD' or the same as the userid. The default is to use 'NO PASSWORD'.

5.8.5 Processing the batch file for creating pupil accounts

If properly configured, the local systems administrator (Freddie Frinton), is allowed to escalate his own privileges to those of the root account using sudo(1). See section 21.3 Managing privileges via sudo in chapter V. Configuring all ServerAtSchool components in the ServerAtSchool Installation Guide for more information.

If you have checked the contents of the shell script and the batch input file, perhaps by using the editor vi(1) or nano(1), you can actually execute the shell script. After processing the files, they can be deleted. The whole process is shown in the illustration below, with your input emphasised.

[ffrint@praeceptor ffrint]$ sudo -s
Password:
[root@praeceptor ffrint]# nano /var/tmp/file20050831231325.sh
[root@praeceptor ffrint]# nano /var/tmp/file20050831231325.in
[root@praeceptor ffrint]# /var/tmp/file20050831231325.sh
grade12:519:grade12:Pupils 1+2:/home/userdata/./home/users/grade12:/sbin/nologin
:programs::NO PASSWORD:/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
grade3:520:grade3:Pupils 3:/home/userdata/./home/users/grade3:/sbin/nologin:prog
rams::NO PASSWORD:/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
grade4:521:grade4:Pupils 4:/home/userdata/./home/users/grade4:/sbin/nologin:prog
rams::NO PASSWORD:/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
grade5:522:grade5:Pupils 5:/home/userdata/./home/users/grade5:/sbin/nologin:prog
rams::NO PASSWORD:/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
grade6:523:grade6:Pupils 6:/home/userdata/./home/users/grade6:/sbin/nologin:prog
rams::NO PASSWORD:/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
grade7:524:grade7:Pupils 7:/home/userdata/./home/users/grade7:/sbin/nologin:prog
rams::NO PASSWORD:/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
grade8:525:grade8:Pupils 8:/home/userdata/./home/users/grade8:/sbin/nologin:prog
rams::NO PASSWORD:/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
abigail:526:grade6:Abigail Adams,00445,19961012:/home/userdata/./home/users/abig
ail:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/
24
alexander:527:grade8:Alexander McKay,00541,19941126:/home/userdata/./home/users/
alexander:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.1
7.2.0/24
alice:528:grade8:Alice Longworth,00472,19940815:/home/userdata/./home/users/alic
e:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
alicia:529:grade8:Alicia Boole,00434,19940912:/home/userdata/./home/users/alicia
:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
andre:530:grade5:Andre Marie Ampere,00598,19970712:/home/userdata/./home/users/a
ndre:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0
/24
andrew:531:grade7:Andrew Reese,00549,19950922:/home/userdata/./home/users/andrew
:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
bipin:532:grade12:Bipin Chandra,00548,20010113:/home/userdata/./home/users/bipin
:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
branwell:533:grade7:Branwell Bronte,00560,19950917:/home/userdata/./home/users/b
ranwell:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.
2.0/24
caroline:534:grade3:Caroline Lucretia Herschel,00423,19990520:/home/userdata/./h
ome/users/caroline:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.
0/8,172.17.2.0/24
catharina:535:grade3:Catharina Giacomo,00439,19991015:/home/userdata/./home/user
s/catharina:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172
.17.2.0/24
catherine:536:grade5:Catherine Hayes,00473,19970701:/home/userdata/./home/users/
catherine:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.1
7.2.0/24
charles:537:grade4:Charles Haddon Spurgeon,00617,19980312:/home/userdata/./home/
users/charles:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,1
72.17.2.0/24
dolly:538:grade3:Dolly Madison,00413,19990121:/home/userdata/./home/users/dolly:
/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
edith:539:grade7:Edith Newborn Jones,00488,19951114:/home/userdata/./home/users/
edith:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
edward:540:grade6:Edward Emerson Barnard,00575,19961120:/home/userdata/./home/us
ers/edward:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.
17.2.0/24
elisabeth1:541:grade5:Elisabeth Inchbald,00451,19970309:/home/userdata/./home/us
ers/elisabeth1:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,
172.17.2.0/24
elisabeth2:542:grade7:Elisabeth Keckley,00508,19950920:/home/userdata/./home/use
rs/elisabeth2:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,1
72.17.2.0/24
elizabeth:543:grade5:Elizabeth Barrett,00440,19970415:/home/userdata/./home/user
s/elizabeth:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172
.17.2.0/24
evita:544:grade3:Evita Peron,00465,19990710:/home/userdata/./home/users/evita:/s
bin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
georgina:545:grade4:Georgina King,00476,19980225:/home/userdata/./home/users/geo
rgina:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
gladys:546:grade3:Gladys Aylward,00481,19990808:/home/userdata/./home/users/glad
ys:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/2
4
hanna:547:grade5:Hanna More,00516,19970612:/home/userdata/./home/users/hanna:/sb
in/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
harold:548:grade6:Harold Bell Wright,00519,19960915:/home/userdata/./home/users/
harold:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2
.0/24
henrietta:549:grade7:Henrietta Barnett,00502,19951106:/home/userdata/./home/user
s/henrietta:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172
.17.2.0/24
herbert:550:grade3:Herbert Spencer,00557,19990206:/home/userdata/./home/users/he
rbert:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
horace:551:grade8:Horace Beam Piper,00592,19940612:/home/userdata/./home/users/h
orace:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
howard:552:grade4:Howard Carter,00543,19981107:/home/userdata/./home/users/howar
d:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
irving:553:grade12:Irving J. Gill,00539,20000313:/home/userdata/./home/users/irv
ing:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/
24
isabelle:554:grade5:Isabelle Sojourner,00444,19970509:/home/userdata/./home/user
s/isabelle:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.
17.2.0/24
khalil:555:grade4:Khalil Gibran,00610,19981108:/home/userdata/./home/users/khali
l:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
ludovico:556:grade3:Ludovico Ferrari,00595,19990313:/home/userdata/./home/users/
ludovico:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17
.2.0/24
martha:557:grade8:Martha Jane Cannary,00428,19940710:/home/userdata/./home/users
/martha:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.
2.0/24
mary1:558:grade12:Mary Fields,00514,20010408:/home/userdata/./home/users/mary1:/
sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
mary:559:grade6:Mary Wollenstonecraft,00452,19960917:/home/userdata/./home/users
/mary:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
may:560:grade12:May Sinclair,00479,20000127:/home/userdata/./home/users/may:/sbi
n/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
michael:561:grade6:Michael Faraday,00525,19960113:/home/userdata/./home/users/mi
chael:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
miriam:562:grade5:Miriam Louise Rothschild,00418,19970511:/home/userdata/./home/
users/miriam:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,17
2.17.2.0/24
oliver:563:grade4:Oliver Heaviside,00536,19980606:/home/userdata/./home/users/ol
iver:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0
/24
simon:564:grade12:Simon Newcomb,00568,20000325:/home/userdata/./home/users/simon
:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
sri:565:grade3:Sri Nisargadatta Mahara,00561,19991127:/home/userdata/./home/user
s/sri:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
virginia:566:grade6:Virginia Woolf,00459,19960710:/home/userdata/./home/users/vi
rginia:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2
.0/24
william1:567:grade7:William Blake,00532,19950727:/home/userdata/./home/users/wil
liam1:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.
0/24
william2:568:grade3:William Bradford,00551,19990722:/home/userdata/./home/users/
william2:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17
.2.0/24
william3:569:grade7:William R. Morris,00570,19950805:/home/userdata/./home/users
/william3:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.1
7.2.0/24
william4:570:grade6:William Tilghman,00586,19960706:/home/userdata/./home/users/
william4:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17
.2.0/24
029 succes adding users from file '/var/tmp/file20050831231325.in'
[root@praeceptor ffrint]# rm /var/tmp/file20050831231325.sh
[root@praeceptor ffrint]# rm /var/tmp/file20050831231325.in
[root@praeceptor ffrint]# exit
[ffrint@praeceptor ffrint]$ _

All the new user accounts are now created and the generated files are removed.

NOTICE: If something goes horribly wrong with adding all the pupil accounts, indicated by a long list of error messages or otherwise, you may need to start again with uploading the file 2005-2006.TXT, resolving name clashes and generating a fresh batch file. However, in that case you must first remove spurious pupil accounts that may have been created accidentially during the failed attempt. You could use a command like this to remove a set of pupil accounts: janitor userdel -r abigail alexander alice alicia andre andrew and repeat it with the other account names that need to be removed.

The result of this mass addition of accounts is best illustrated using the web interface. In Janitor, navigate to: main menu | users and groups | modify users and groups | nests. The following appears on the screen.

janitor_upload_pupils7.png

All accounts for this schoolyear have now been created: the staff using a batch file (section 5.7 Adding multiple user accounts) and all pupils using the file upload feature discussed here.

NOTICE: At this point the teachers and the grades can be linked, i.e. the accounts of the teachers can be modified in such a way that the teachers become members of 'grade12' and/or 'grade3' and/or 'grade4' etcetera. This can be done using the procedure outlined in section 5.5 Modifying a user account above, adding the appropriate secondary groups to the teacher accounts. This could not be done earlier because nests (grades) did not yet exist.

5.9 Promoting nests (grades) manually

Before a grade (nest) can be promoted (say pupils from 'grade3' are to be promoted to 'grade4') the target nest should exist. In the case of 'grade3' this is probably not a problem. However, what to do with pupil accounts of the old 'grade8' (the last grade at this school)? This question is discussed shortly.

Another problem is that if 'grade3' is promoted to 'grade4', the pupils of both grades are merged in 'grade4'. This makes it hard to promote the pupils from 'grade4' to 'grade5' because the new 'grade4' (the old 'grade3') is combined with the old 'grade4'. Therefore it is best to work backwards, i.e. first get rid of the pupils in 'grade8', then promote 'grade7' to 'grade8', then promote 'grade6' to 'grade7', etcetera.

5.9.1 Preparing for promoting pupils of grade 8

1. Delete the accounts
   An easy way to get rid of the obsolete accounts of the pupils of the old grade 8 is to simply delete the accounts, including upto 8 years of work per pupil, as per the procedure described in section 5.6.2 Deleting a pupil account.
2. Retain the accounts for 1 more year
   In this case you should create a special nest, say 'alumni'. At the end of the schoolyear you can promote the pupils of the old 'grade8' to the nest 'alumni'. This way all the work of the ex-pupils (their 'portfolio') is saved, for future reference. After a year, the pupils in this nest 'alumni' are deleted and the new 'grade8' is promoted to 'alumni'. You can consider this a service to the ex-pupils; they might not realise that they want to keep their school stuff until they are at their new school.
3. Retain all accounts forever
   If you have the disk space on the server you might opt for keeping all accounts, forever. A workable solution for this case might be to add a special nest every year, say 'class2005', class2006', class2007', etc. The pupils of 'grade8' in the schoolyear 2004-2005 (the 'Class of 2005') could then be promoted to the nest called 'class2005'.

Here we opt for option 2: retaining the accounts for one more year. In this case you should do the following.

• If the nest 'alumni' already exists, you should delete all pupil acounts in this grade. These are the pupil accounts of last year's 'grade8'. Use the procedure discussed in 5.6.2 Deleting a pupil account for all ex-pupils in the 'alumni' nest.
• If the nest 'alumni' does not yet exist, you should create it. Use the procedure explained in section 5.3 Adding a nest (grade) account. You could use the following values:
  • UserID: 'alumni'
  • Full name: Former Pupils
  • Group: same as userid (default)
  • SMB Password: none
  • Home directory: normal (default)
  • Login shell: none (default)
  • Webmail access: none

At this point you are ready to begin with promoting the pupils of 'grade8' to the nest 'alumni' and then proceed with 'grade7', 'grade6', etcetera.

5.9.2 Promoting pupils via the web interface

janitor_promote_pupils1.png

You can now start promoting the pupils starting at the end and working backwards. Here, start with 'grade8'. Follow the second link labeled 'grade8'. This is the link in the column labeled 'group'. The following appears on the screen.

janitor_promote_pupils2.png

In this screen you see the list of all pupils in the selected grade (here: 'grade8'): 'alexander', 'alice', 'alicia', 'horace' and 'martha'. Note that by default all check boxes in the column 'move' are checked. At the bottom of the screen there is a drop down box. You can select the correct target nest here. In the illustration the nest 'alumni' has already been selected. All pupils are ready to be promoted because all names are checked. If one of the pupils would flunk and have to redo the year, you would simply uncheck the corresponding box and not promote that pupil. Press the [Move] button to actually promote the pupils to the selected target nest. The following appears on screen.

janitor_promote_pupils3.png

You are back in the overview of all nests. Note the remark at the top of the page ('Success moving selected members from group 'grade8' to 'alumni''). This indicates that the pupils are indeed promoted. You can also see that a new nest is visible at the top of the list (the 'alumni' nest). Also note that the nest called 'grade8' is missing. This is due to the fact that an empty nest is transformed into a regular account as soon as there are zero pupils in the grade.

After moving pupils from 'grade8' to 'alumni' and creating this empty nest, you can proceed to promote the pupils of 'grade7' to 'grade8' by repeating the procedure.

5.9.3 Promoting pupils via the command line

[ffrint@praeceptor ffrint]$ janitor usermod -g grade8 andrew
[ffrint@praeceptor ffrint]$ janitor usermod -g grade8 branwell
[ffrint@praeceptor ffrint]$ janitor usermod -g grade8 edith
[ffrint@praeceptor ffrint]$ janitor usermod -g grade8 elisabeth2
[ffrint@praeceptor ffrint]$ janitor usermod -g grade8 henrietta
[ffrint@praeceptor ffrint]$ janitor usermod -g grade8 william1
[ffrint@praeceptor ffrint]$ janitor usermod -g grade8 william3
[ffrint@praeceptor ffrint]$ _

At this point these pupils are promoted to 'grade8' and 'grade7' is now an empty nest.

There is a way to promote a list of pupils in a single command. This is illustrated below: all pupils of 'grade6' ('abigail', 'edward', 'harold', 'mary', 'michael', 'virginia' and 'william4') are promoted to 'grade7'.

[ffrint@praeceptor ffrint]$ janitor usermod -g grade7 abigail edward harold mary michael virginia william4
[ffrint@praeceptor ffrint]$ _

This saves some typing because you do not have to issue one command per pupil but only one command per nest (grade).

Note that you can use either method to promote pupils; in the end the results are the same.

5.10 Promoting nests (grades) via file upload

This upload feature is able to 'recognise' existing pupil accounts and update those accounts using the information from the uploaded file.

The procedure is as follows.

• the oldest pupils (in 'grade8') have to be promoted or removed from the system
• the file with pupil data for the next schoolyear has to be uploaded using the web interface
• name clashes and other issues need to be resolved using the web interface
• a batch file is constructed using the web interface
• the batch file is processed at the command line

The following assumes that the accounts of the pupils in the old 'grade8' have already been moved to the nest called 'alumni'. See section 5.9.1 Preparing for promoting pupils of grade 8 for an in-depth discussion. The effect is that the nest 'grade8' is now an empty nest, ready to receive the new pupils that are being promoted from 'grade7'.

5.10.1 Uploading the file with new pupil's data

janitor_promote_upload1.png

Explanation:

• Fileformat: select 1 of the 4 file formats. Default value is 'Fixed Record Length'. Other options are 'CSV (dateformat=YY/MM/DD)', 'CSV (dateformat=MM/DD/YY)' and 'CSV (dateformat=DD/MM/YY)'.
• Filename: use the [Browse] button to select the file containing the data to upload (already done in the illustration).
• Field definitions: two sets of field definitions can be defined. Your choice for 'Fileformat' determines which definition is used.
  • Fixed start: this defines the starting position of a field (1 means the first position of the line)
  • Fixed length: this defines the length of a particular field.
  • CSV index: this defines the number of the field within the comma delimited line (1 means the first field)
• Unique key: the unique identifier for the pupil
• First name: the first name of the pupil
• Infix: the infix of the pupil's name (if any)
• Last name: the last name of the pupil
• Grade: the pupils grade (class)
• Birthday: pupil's birthday. The format should match the choice made in 'Fileformat' above. This field is used only for comma delimited upload files.
• Birthday (year, month, day): pupil's birthday split into individual components. This is only relevant for fixed record length upload files.

NOTICE: You can change the defaults in this upload screen, see section 7.2 Tweaking the web interface via config.php below. The distribution defaults correspond the EDEX format as mentioned before.

5.10.2 Preparing the pupil's new data

janitor_promote_upload2.png

This screen consists of two (long) tables. The first table is a list of existing nests and nests-to-be. This table is labeled 'groups'. The second table contains a list of all existing pupil accounts and pupil-accounts-to-be. This table is labeled 'users'.

The first table ('groups') has three columns.

• ID: This is the (unique) identifier of a grade. It is used to link pupils to nests (grades).
• Groupname: This is the suggested name of the nest (grade). Note that by default the name of the grade consists of the word 'grade' followed by the ID in the previous column. This field can be edited so you can change the default name into something else ('ladybirds' instead of 'grade1', 'fireflies' instead of 'grade3', etc.).
• Comments: This is the place where Janitor shows comments when something is wrong with this particular grade.

The second table ('users') has four columns.

• ID: This column shows the unique identifier of a pupil, e.g. '00445' for pupil 'Abigail Adams'. It also shows the grade of this pupil between parentheses, e.g. '(7)'. Note that this links the pupil to the nest (grade) in the previous table.
• UserID: This is the suggested userid that will be used for this pupil. Note that this userid is based on the first name of the pupil. This field can be edited.
• Full Name: This is the suggested Full name of the pupil. It is constructed using first name, infix and last name from the uploaded file. This field can be edited.
• Comments: This is the place where Janitor shows comments when something is wrong with this particular pupil account.

The message in red ('More editing required') at the top of the screen indicates that there are some issues that need to be resolved before the accounts can be modified or created. This issues are identified with different background colours. The following colour coding is used:

• Blue: the information in the record (pupil or nest) looks acceptable; this proposed (new) account does not conflict with existing accounts and obeys all the rules for account names etc.
• Yellow: the information in the record (pupil or nest) looks acceptable and furthermore, because an account of this name already exists, the existing account will be updated rather than duplicated under another name.
• Orange: this account (pupil or nest) requires special attention. It could be a nest that combines two different grades (e.g. grade 1 and grade 2 in the same nest 'grade12'). It could also be an indication of a pupil account that already exists but under another name.
• Red: the information for this account is not acceptable: either another (and completely different) account with the same name already exists, the suggested name is not acceptable due to embedded punctuation (dots, dashes, etc.) or spaces or there are other anomalies with this proposed new account.

The bottom of this screen (not shown in the illustration) has two buttons: [Recalculate] and [Cancel]. After editing the appropriate fields ('Groupname', 'UserID' or 'Full Name') you can press the [Recalculate] button. This instructs Janitor to re-evaluate the collection of new accounts and the proposed modifications to existing accounts. Any conflicts that yield a 'red' background must be resolved. Issues in an 'orange' background are mere warnings but are acceptable as far as Janitor is concerned.

5.10.3 Resolving name clashes and other issues

• Mary Wollensctonecraft (grade 6) was issued the suggested userid 'mary'.
• Mary Fields (grade 1) was issued the userid 'mary1'.

janitor_promote_upload3.png

You see that 'mary1' is recognised by Janitor; the background colour is yellow. However, the userid 'mary' is already taken and the new Mary Kingsley has to have another userid. You may want to try and streamline the three mary's by assigning the userids 'mary1', 'mary2' and 'mary3'. However, after pressing the [Recalculate] button Janitor shows the following.

janitor_promote_upload4.png

The situation got worse. It now looks like the existing 'mary1' is recognised (good) and the new Mary Kingsley will have userid 'mary2' (also good) but the existing account of Mary Wollenstonecraft is on the verge of being recreated under another name. Note that Janitor identifies the account of Mary Wollenstonecraft as an existing account both by using an orange background colour and also the comment 'this account already exists as 'mary' (Mary Wollenstonecraft, 00452, 19960917)'. The reference number ('00452') and the date of birth can help identify the exact pupil.

The effect of duplicating the account for this Mary (the account 'mary3') in grade 7 would be that her 'My Documents' would no longer contain the work she created in grades 1 to 6 because that would still be associated with the userid 'mary'. This once again illustrates that a userid has to be selected carefully (see the earlier discussion in section 5.8.3 Preparing the pupil's data above).

The best solution in this case is to keep the existing accounts 'mary' and 'mary1' and assign 'mary2' to the new kid on the block. After pressing the [Recalculate] button, Janitor now shows the following screen.

janitor_promote_upload5.png

Note that the two existing accounts are re-used (yellow background) whereas a new account 'mary2' is newly created (blue background).

In the meantime another problem needed to be solved, too. The name for the combined grade 1 + 2 was not recreated automatically. This has to be done by hand. If you do not change the 'Groupname' of both grade 1 and grade 2 into 'grade12', you end up with two new nests, called 'grade1' and 'grade2'.

After making these last adjustments and pressing the [Recalculate] button once again, Janitor displays the following screen.

janitor_promote_upload6.png

The red message at the top of the screen 'Everything looks OK' indicates that Janitor has not detected any more issues with the pupil's data. Note that there now is a third button [Generate] at the bottom of the screen. Pressing this button generates a batch file and a script that has to be processed at the command line.

NOTICE: The whole procedure, from uploading a file upto the moment that you can press the [Generate] button has to take place in a single session. There is no way to save your changes and continue lateron.

5.10.4 Generating the batch file for creating and updating accounts

janitor_promote_upload7.png

Janitor's message in red now reads: 'Everything is OK: results written in file /var/tmp/file20050906152456'. The remainder of the screen shows the contents of two files and an [OK] button at the end. The first file is a shell script called '/var/tmp/file20050906152456.sh'. The contents starts with a single instruction, namely the janitor useradd command with the switch -b followed by the name of the second file. This command adds the new accounts such as that for 'mary2'. After that single instruction a long list follows with instructions that modify the existing accounts. You can see that pupil 'abigail' is placed in grade7 using the -g switch.

The second file is called '/var/tmp/file20050906152456.in'. This is a batch input file which conforms to the format discussed earlier (in section 5.7.1 File format for batch processing). The contents of this file corresponds to the data of all new accounts which was prepared in the previous sections. This is illustrated below.

janitor_promote_upload8.png

The shell script has to be executed at the command line, e.g. by the local systems administrator (Freddie Frinton). It is necessary to do this using the root account or at least with root privileges because the files created are not readable by members of the group 'janitors'. Making the procedure of creating the pupil accounts a two-step process is a security measure. It gives the local systems administrator an opportunity to examine the batch file before it is processed.

After pressing the [OK] button you return to Janitor's main menu.

5.10.5 Processing the batch file for creating and updating pupil accounts

If properly configured, the local systems administrator (Freddie Frinton), is allowed to escalate his own privileges to those of the root account using sudo(1). See section 21.3 Managing privileges via sudo in chapter V. Configuring all ServerAtSchool components in the ServerAtSchool Installation Guide for more information.

If you have checked the contents of the shell script and the batch input file, perhaps by using the editor vi(1) or nano(1), you can actually execute the shell script. After processing the files, they can be deleted. The whole process is shown in the illustration below, with your input emphasised.

[ffrint@praeceptor ffrint]$ sudo -s
Password:
[root@praeceptor ffrint]# nano /var/tmp/file20050906152456.sh
[root@praeceptor ffrint]# nano /var/tmp/file20050906152456.in
[root@praeceptor ffrint]# /var/tmp/file20050906152456.sh
caesar:572:grade12:Caesar Rodney,00583,20020103:/home/userdata/./home/users/caes
ar:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/2
4
jaroslav:573:grade12:Jaroslav Seifert,00603,20020407:/home/userdata/./home/users
/jaroslav:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.1
7.2.0/24
mary2:574:grade12:Mary Kingsley,00495,20020716:/home/userdata/./home/users/mary2
:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/24
thomas:575:grade12:Thomas Johnson,00579,20020619:/home/userdata/./home/users/tho
mas:/sbin/nologin::::/home/userdata/home/skeletons/skel::127.0.0.0/8,172.17.2.0/
24
029 succes adding users from file '/var/tmp/file20050906152456.in'
[root@praeceptor ffrint]# exit
exit
[ffrint@praeceptor ffrint]$ _

NOTICE: It may take a while when many pupils are promoted.

NOTICE: See also section 5.8 Adding multiple pupils via file upload for information on using this file upload feature. Technically there really is not much difference between the procedure for adding new pupil accounts and updating existing pupil accounts.

(top)

6. Managing CD-ROM images

6.1 Creating .iso-files via the web interface

• Place the CD-ROM in the CD-ROM player in the server computer
• Create the .iso-file using the procedure discussed below
• Remove the CD-ROM from the CD-ROM player

janitor_cdrom_image1.png

Explanation:

• There is an input field labeled 'Image name' where you can enter the name of the CD-ROM image. If you do not add the .iso extension, it is added automatically. Here the name 'edurithmetic' is already entered.
• A list with the names of existing CD-ROM images is shown. In this example images had already been made of the following CD-ROMs: 'eduread', 'kameleon' and 'edurite'.
• There are two buttons at the bottom of the screen: [Start] to begin the process and [Cancel] to bail out and return to the tools menu.

NOTICE: If you wish you can use names with embedded spaces, allthough this is discouraged. It is recommended to use names (without spaces) as short as possible. For instance: the CD-ROM with the reading software called 'Roberta's Reading Ralley' could be stored under the name RobertasReadingRalley.iso or if you insist Roberta's Reading Ralley.iso. However, these are very long names which might generate problems lateron. On the other hand RRR.iso might be too short and not give enough indication about which CD-ROM this might be if you return to it in 6 months. Perhaps RobertaRR.iso would be the best choice in this particular case.

You can start the process by pressing the [Start] button. A screen like the following appears.

janitor_cdrom_image2.png

This screen indicates that a background process is being started. This screen is refreshed automatically every 10 seconds, showing you the progress by displaying the number of bytes copied sofar (here: 67,313,664 bytes or some 65 MB). Note that it may take a while to create the .iso-file; a CD-ROM can easily contain up to 700 MB of data.

After the complete CD-ROM has been processed, the following image appears.

janitor_cdrom_image3.png

NOTICE: The .iso files are stored in the directory /home/share/iso as determined by the configuration file /etc/janitor/janitor.conf. This directory is shared with the network as a Samba-share called 'cdroms'. This share is usually assigned the Windows drive letter R:. Therefore, you can refer to the CD-ROM image from a Windows client computer as R:\edurithmetic.iso.

NOTICE: Messages from Janitor all have a number like '057' and '061'. This makes it easier to parse the output from Janitor with another program even if the messages themselves would have been translated into another language. A complete list of message can be found in /etc/janitor/janitor.msg. Further discussion of this mechanism is beyond the scope of this manual.

6.2 Creating .iso-files via the command line

[ffrint@praeceptor ffrint]$ janitor cdimage edutraffic.iso
063 process started in the background
[ffrint@praeceptor ffrint]$ janitor cdimage
057 process 20584 started Wed Sep 7 15:04:04 CEST 2005
060 Wed Sep 7 15:04:04 CEST 2005 start copying from /dev/cdrom to /home/share/iso/edutraffic.iso
064 Wed Sep 7 15:05:18 CEST 2005 (20584): /home/share/iso/edutraffic.iso 137830400 bytes
[ffrint@praeceptor ffrint]$ janitor cdimage
057 process 20584 started Wed Sep 7 15:04:04 CEST 2005
060 Wed Sep 7 15:04:04 CEST 2005 start copying from /dev/cdrom to /home/share/iso/edutraffic.iso
061 results: 458308+0 records in 458308+0 records out
062 Wed Sep 7 15:05:41 CEST 2005 done copying /dev/cdrom to /home/share/iso/edutraffic.iso (234653696 bytes)
065 no background process is running
[ffrint@praeceptor ffrint]$ _

6.3 Removing CD-ROM images

(top)

7. Advanced topics

7.1 Tweaking Janitor via janitor.conf

This main configuration file is copied in a form that is easily understood by the web interface program. This copy of the configuration file in another format is stored in /home/httpd/janitor/config/janitor.conf.php. This copy can be regenerated using janitor(1) as illustrated below. Your input is emphasised.

[ffrint@praeceptor ffrint]$ janitor configphp
050 success (re)writing '/home/httpd/janitor/config/janitor.conf.php'
[ffrint@praeceptor ffrint]$ _

After issuing that command the configuration file janitor.conf.php may look like this. The lines of interest are emphasised in the illustration below.

<?php
# /home/httpd/janitor/config/janitor.conf.php -- Janitor configuration file for PHP interface 
#
# This file is generated from /etc/janitor/janitor.conf on 2005-08-28 20:12
#
#   Copyright (C) 2004-2005 Peter Fokker, <peter@berestijn.nl>
#
#   This file is part of Janitor.
#
#   Janitor is free software; you can redistribute it and/or modify
#   it under the terms of the GNU General Public License as published by
#   the Free Software Foundation; either version 2 of the License, or
#   (at your option) any later version.
#
#   Janitor is distributed in the hope that it will be useful,
#   but WITHOUT ANY WARRANTY; without even the implied warranty of
#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#   GNU General Public License for more details.
#
#   You should have received a copy of the GNU General Public License
#   along with this program; if not, write to the Free Software
#   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#

$jcfg = array(
        "BUDDIES_GID" => "96",
        "BUD_HOME" => "home",
        "BU_DAILY" => "4",
        "BU_HOURLY_BEGIN" => "7",
        "BU_HOURLY_END" => "18",
        "BU_OFFSET" => "6",
        "CHROOT_BUDDIES" => "/home/buddies",
        "CHROOT_BUDDIES_FILES" => "/etc/janitor/buddies_files.conf",
        "CHROOT_USERDATA" => "/home/userdata",
        "CHROOT_USERDATA_FILES" => "/etc/janitor/userdata_files.conf",
        "EXIM_ALIASES" => "/etc/exim/aliases",
        "EXIM_NEWALIASES" => "/usr/sbin/newaliases",
        "FULL_DOMAIN" => "exemplum.serveratschool.net",
        "GID_EXP" => "94 95 96 97 98",
        "GID_MAX" => "45499",
        "GID_MIN" => "100",
        "GID_UPG" => "499",
        "HTTPD_GROUP" => "www",
        "HTTPD_USERID" => "www",
        "INSTALL_GID" => "95",
        "INTERNAL_ADDR" => "172.17.2.0/24",
        "JANITORCD_DEV" => "/dev/cdrom",
        "JANITORCD_DIR" => "/home/share/iso",
        "JANITORCD_EXT" => ".iso",
        "JANITORCD_LNK" => "janitorcd.lnk",
        "JANITORCD_LOG" => "janitorcd.log",
        "JANITORCD_PID" => "janitorcd.pid",
        "JANITORCD_RUN" => "/var/run/janitor",
        "JANITORS" => "janitors",
        "JANITORS_GID" => "98",
        "JANITOR_CONF_PHP" => "/home/httpd/janitor/config/janitor.conf.php",
        "JANITOR_INIT" => "/etc/janitor/janitor_init.txt",
        "JANITOR_LANG" => "EN",
        "JANITOR_MSG" => "/etc/janitor/janitor.msg",
        "PHP_ALLOWED_REMOTE_ADDR" => "127.0.0.0/8,172.17.2.0/24",
        "PROGRAMS" => "programs",
        "PROGRAMS_GID" => "94",
        "SMB_BACKUP" => "My Backups",
        "SMB_DESKTOP" => "Desktop",
        "SMB_HOME" => "H",
        "SMB_MYDOCUMENTS" => "My Documents",
        "SMB_NESTS" => "nests",
        "SMB_PROFILE" => ".profile",
        "SMB_STARTMENU" => "Start Menu",
        "SQM_ALLOWED_REMOTE_ADDR" => "allowed_remote_addr",
        "SQM_EMAIL_ADDRESS" => "email_address",
        "SQM_FULL_NAME" => "full_name",
        "SQM_PREFS_DEFAULT" => "default_pref",
        "SQM_PREFS_DIR" => "/usr/lib/squirrelmail/prefs",
        "SQM_PREFS_EXT" => ".pref",
        "SUB_BACKHOME" => "backhome",
        "SUB_GROUPS" => "groups",
        "SUB_HOME" => "home",
        "SUB_SHORTCUTS" => "shortcuts",
        "SUB_SKEL" => "skel",
        "SUB_SKELETONS" => "skeletons",
        "SUB_USERS" => "users",
        "TELEWORKERS_GID" => "97",
        "UID_EXP" => "",
        "UID_MAX" => "45499",
        "UID_MIN" => "501",
        "JDATE" => "2005-08-28 20:12");
?>

Explanation:

• JANITOR_LANG
  This parameter (default value: 'EN') determines the language of the Janitor interface. By default the language is English. If you want to use Janitor in another language, the appropriate file corresponding with the chosen language must exist in /home/httpd/janitor/language. By default only EN.php exists.
• PHP_ALLOWED_REMOTE_ADDR
  This parameter defines the IP-addresses from which the Janitor web interface may be accessed. Default value is: '127.0.0.0/8,172.17.2.0/24'. This means that access is allowed from the LAN and also from the server itself. No access from the outside is allowed by default. If you want to allow access from IP-address 192.0.34.166 too, you would want to change this parameter into '127.0.0.0/8,172.17.2.0/24,192.0.34.166/32'. This way you can allow your ICT coordinator (Amelia Cackle at the Exemplum Primary School) to work with the Janitor web interface from her internet connection at home (which has IP-address 192.0.34.166).

NOTICE: It is important to note that the changes in the configuration should be done via the main configuration file /etc/janitor/janitor.conf. After that, the changes take effect as soon as the command 'janitor configphp' is executed. If you make changes to the file /home/httpd/janitor/config/janitor.conf.php directly, these changes are overwritten the next time the command 'janitor configphp' is executed.

7.2 Tweaking the web interface via config.php

<?php
//  config.php -- program specific settings
//
//  $Id: config.php,v 1.14 2005/08/25 11:46:52 peter Exp $
//
//  Copyright (C) 2004,2005 Peter Fokker, <peter@berestijn.nl>
//
//  This file is part of Janitor.
//
//  Janitor is free software; you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation; either version 2 of the License, or
//  (at your option) any later version.
//
//  Janitor is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with this program; if not, write to the Free Software
//  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
//
// 2005-08-25/PF - updated version number to 0.9.6

define("APP_NAME",              "Janitor"       );
define("APP_VERSION",           "0.9.6"         );
define("APP_DATE",              "2005-08-25"    );
define("APP_BGCOLOR",           "#FFFFAF"       );
define("APP_TEXT",              "#000000"       );
define("APP_LINK",              "#0000CF"       );
define("APP_VLINK",             "#0000CF"       );
define("APP_ALINK",             "#FF0000"       );
define("APP_ERRCOLOR",          "#FFAFAF"       );
define("APP_MSGCOLOR",          "#FF3F3F"       );
define("APP_TITLECOLOR",        "#CFCFCF"       );
define("APP_NAVCOLOR",          "#CFCFCF"       );
define("APP_BUTCOLOR",          "#CFCFFF"       );
define("APP_EDEXOK",            "#CFCFFF"       ); // used in Edex import
define("APP_EDEXWARN1",         "#FFFF6F"       ); // used in Edex import
define("APP_EDEXWARN2",         "#FFCF6F"       ); // used in Edex import
define("APP_EDEXERR",           "#FFAFAF"       ); // used in Edex import
define("PAGE_FOOTER",           ""              ); // displayed on every page, if non-empty, including timestamp 

define("ACTION_LOGIN",          "login"         );
define("ACTION_LOGOUT",         "logout"        );
define("ACTION_MENU",           "menu"          );
define("ACTION_SCREEN",         "screen"        );
define("ACTION_PROCESS",        "process"       );
define("PARAM_SRC",             "s"             );
define("PARAM_TGT",             "t"             );
define("PARAM_USER",            "u"             );
define("PARAM_GROUP",           "g"             );
define("PARAM_ACTION",          "action"        );
define("PARAM_BUTTON",          "button"        );

define("BUTTON_SAVE",           __(" Save ")    );
define("BUTTON_CANCEL",         __(" Cancel ")  );
define("BUTTON_YES",            __(" Yes ")     );
define("BUTTON_NO",             __(" No ")      );
define("BUTTON_OK",             __(" OK ")      );
define("BUTTON_DELETE",         __(" Delete ")  );
define("BUTTON_MOVE",           __(" Move ")    );
define("BUTTON_START",          __(" Start ")   );
define("BUTTON_REFRESH",        __(" Refresh ") );
define("BUTTON_UPLOAD",         __(" Upload ")  );
define("BUTTON_RECALC",         __(" Recalculate "));
define("BUTTON_GENERATE",       __(" Generate "));

define("ACTION_USERGROUP",      "usersgroups"   );
define("ACTION_SHORTCUTS",      "shortcuts"     );
define("ACTION_REGEDIT",        "regedit"       );
define("ACTION_MAKEISO",        "makeiso"       );
define("ACTION_UG_OVERVIEW",    "overview"      );
define("ACTION_UG_GROUPADD",    "groupadd"      );
define("ACTION_UG_GROUPDEL",    "groupdel"      );
define("ACTION_UG_USERADD",     "useradd"       );
define("ACTION_UG_USERMOD",     "usermod"       );
define("ACTION_UG_USERDEL",     "userdel"       );
define("ACTION_UG_GROUPEDIT",   "ugedit"        );
define("SESSION_SAVEPATH",      "/var/tmp"      );
define("EXTRA_FIELDS",          2               ); // was 5, set to 2 while creating documentation
define("EXTRA_GROUPS",          32              );
define("SPARE_GROUPS",          3               );
define("EMAIL_ALIASES",         5               );

// See $fileformat and $fieldlist in edex.php for more information
// on $edex_defaults and related parameters.
$edex_defaults = array( 0 => 1,                                 // default fileformat: 1=Fixed Record Length
                        1 => array(     81,     5,      1),     // unique key
                        2 => array(     51,     20,     2),     // first name
                        3 => array(     41,     10,     3),     // infix
                        4 => array(      1,     40,     4),     // last name
                        5 => array(     86,     5,      5),     // grade (class)
                        6 => array(      0,     0,      6),     // birthday (CSV only)
                        7 => array(     77,     2,      0),     // dob.year (Fixed only)
                        8 => array(     74,     2,      0),     // dob.month (Fixed only)
                        9 => array(     71,     2,      0));    // dob.day (Fixed only)
$grade_prefix = __('grade');    // this variable is used to prefix a non-alpha grade field (field 5)
$grade_pupils = __('Pupils');   // used in generating grade accounts in edex.php
$grade_passwd = 1;              // 0=none at all,1='NO PASSWORD',2=same as userid

//  eof
?>

Explanation:

• EXTRA_FIELDS
  This parameter determines the number of extra fields that are visible in the web interface. The default value for this parameter is 5. However, in an attempt to keep all images in this documentation at least a little readable this value was lowered to 2. Two of the extra fields are used in the pupil's data file upload. Therefore it is handy to configure this value to at least 2 extra fields.
• SPARE_GROUPS
  Any user can be a member of at most 32 secondary groups at a single time. However, many users never have more than a handful of secondary groups. In order to keep the web interface as clean as possible, the number of secondary groups visible in the interface is limited to the current number of secondary groups the user is a member of plus the number of spare groups defined with this parameter. The default value is 3.
• EMAIL_ALIASES
  This parameter determines the maximum number of e-mail aliases that can be assigned to a user via the web interface. The default is 5 aliasses. Note that the first alias also used as the sender address in Squirrelmail. Therefore do not set this value to less than 1.
• $edex_defaults
  This array determines the default values for the pupil's data file upload feature (see sections 5.8 Adding multiple pupils via file upload and 5.10 Promoting nests (grades) via file upload above).
  • Array element 0 (value = 1) determines the default type of file upload. Possible values are:
    1 = Fixed Record Length
    2 = CSV (dateformat=YY/MM/DD)
    3 = CSV (dateformat=MM/DD/YY)
    4 = CSV (dateformat=DD/MM/YY)
  • Array elements 1 - 9 determine the default values for the 9 different fields. These numbers are configured in the same order as they are shown in the interface:
    1st = Fixed start: this defines the starting position of a field (1 means the first position of the line)
    2nd = Fixed length: this defines the length of a particular field.
    3rd = CSV index: this defines the number of the field within the comma delimited line (1 means the first field)
    Note that the numbers with value 0 (zero) are unused.
• $grade_prefix
  This parameter determines the word that is used to prepend to the name of a (new) nest in the pupil's data file upload. By default this word is 'grade' or rather the translation of that word in the selected language (see notice below).
• $grade_pupils
  This parameter determines the word that is used to construct the Full name of a (new) nest in the pupil's data file upload. By default this word is 'Pupils' or rather the translation of that word in the selected language (see notice below). This word is followed by the contents of the appropriate grade field, field number 5. Therefore the default Full name of 'grade8' would be 'Pupils 8'.
• $grade_passwd
  This parameter indicates which SMB password (Windows Networking) is assigned to new nests in the pupil's data file upload. Default value is 1. The possible values are:
  • 0 - no password at all (access to Windows Networking is blocked)
  • 1 - the special value 'NO PASSWORD' which allows the nest to access Windows Networking without a password at all (but the userid still needs to be specified)
  • 2 - the password is the same as the name of the userid, i.e. the password for 'grade4' would be 'grade4'.

NOTICE: The configuration file uses a special function __() at various places, e.g. $grade_prefix = __('grade');. This function is used in Janitor to handle translations of words and phrases. In this example the variable $grade_prefix is assigned the translation of the word 'grade' as it is encountered in the relevant language file in /home/httpd/janitor/language. By changing the translation the parameter is changed, too. Of course it is possible to assign a different word directly, i.e. without going through the language file. Example: $grade_prefix = 'grade';.

NOTICE: The configuration file is 'raw' PHP-code. It is important to leave all semicolons ';' and double quotes '"' and single quotes '''' exactly as-is. If this file is mis-configured, the web interface might stop working (but the command line version would still function). Please make a backup copy of config.php before you make changes to the file.

(top)

8. Conclusion

(top)