III. Janitor

Contents

1. Introduction
    1.1 General remarks
    1.2 Janitor's features
    1.3 Layered approach
    1.4 Overview of this chapter
    1.5 Additional information

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

This chapter documents the Janitor program. This is the tool that is used to manage users and groups. It can also be used to create CD-ROM images for use with DAEMON Tools (see chapter VI. DAEMON Tools virtual CD player).

1.1 General remarks

Most of the tasks Janitor can perform can be done via either the command line (on the server console, from a workstation in the LAN or from a remote location) or via the web interface. Access to the program is limited to users that are a member of a special group called 'janitors'.

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.

1.2 Janitor's features

Janitor has the following features. For every user account the following properties can be set and modified.

1.3 Layered approach

Janitor is constructed in two layers. The first layer consists of the collection of command line programs such as janitorcmd(1). These are accessible via janitor(1). The command line program janitor(1) is only available for users that are a member of the (predefined) group janitors. The root account is also allowed to use the program.

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

This chapter documents Janitor based on real-world tasks that need to be performed rather than summing up all commands in an alphabetic or otherwise illogical order. However, it is likely that the tasks related to group management and user management will occur in more or less the order in which they are described in sections 4 and 5 below. If you want to learn about the possibilities Janitor provides, you should simply read this chapter from beginning to end.

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

The examples in this chapter are based on the Exemplum Primary School (see section 2. The Exemplum Primary School in chapter II. ServerAtSchool User Manual Overview. The data for the population of the Exemplum Primary School was generated with a small utility called edexdata(1). You can use this utility, located in /usr/sbin/janitor/edexdata to regenerate the data and follow all examples in detail in order to get to know the ServerAtSchool system. Of course this is done best on a computer that is not used for production. Note that you need to be root to access this utility.

(top)

2. Authentication

Not every user is allowed to use the Janitor program. Access is limited to the user accounts that are a member of the special predefined 'janitors' group. Good candidates for membership of this group are the local systems administrator (Freddie Frinton, userid ffrint) and the ICT coordinator of the school (Amelia Cackle, userid acackl).

2.1 Login procedure

Authentication in the web interface takes place via a login dialogue where a userid and a password must be entered. The Janitor web interface can be accessed via the school's website, e.g. http://www.exemplum.serveratschool.net/janitor/ or http://praeceptor.exemplum.serveratschool.net/janitor/.

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.

[ login screen for web interface Janitor ]
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.

[ mani menu for web interface Janitor ]
janitor_mainmenu.png

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

2.2 Logout procedure

When you are are logged in in Janitor, you see something like this (here the main menu as an example).

[ mani menu for web interface Janitor ]
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.

[ logout screen for web interface Janitor ]
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

Authenticating at the command line works slightly different. The mere fact that you can succesfully login on the console (i.e. using the keyboard and monitor connected directly to the server) combined with your membership of the 'janitors' group is enough to access the janitor(1) program. The example below illustrates logging in on the console. Your input is emphasised.

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

If the ServerAtSchool server is configured to accept connections from the outside world, it is possible to login to the server using an encrypted connection using SSH. The snippet below illustrates a login from home. Once again your input is emphasised.

[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

After logging in in Janitor the main menu appears on screen.

[ mani menu for web interface Janitor ]
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.

3.1 Users and groups

This submenu looks like this. Here is an example of an overview of all users and groups.

[ overview of users and groups at the beginning ]
janitor_overview.png

3.2 Shortcuts

The shortcuts submenu has the following options. Both options are currently not implemented. Shortcuts on the users' Desktops and in the users' Start Menus are managed via a Windows workstation. See chapter IX. Shortcuts, desktops and start menus.

3.3 Tools

(top)

4. Managing workgroups

Workgroups are used to allow sharing of files and documents between various groups within the school community. Every workgroup is assigned a subdirectory (or folder) on the server. This subdirectory can only be accessed by members of that workgroup. This is a security feature.

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

If you want to add a workgroup, say 'staff', via the web interface you should do the following.

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

[ adding a workgroup via the web interface ]
janitor_add_workgroup1.png

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

[ success adding a workgroup via the web interface ]
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

If you want to add an existing user to an existing workgroup you should do the following. Here is an example of adding user 'ffrint' to both the workgroup 'staff' and 'jubilee'.

[ adding a user to a 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.

[ success adding a user to a workgroup ]
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

You can display an overview of workgroups by navigating to: main menu | users and groups | modify users and groups | workgroups. The following screen appears.

[ deleting 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

An important part of Janitor is managing user accounts or 'users' for short. This means adding users, changing the properties, and removing accounts. This section first discusses the properties a user account can have. After that the various common tasks are discussed in the various subsections.

5.1 General information

5.1.1 Properties of a user account

Here is an overview of the properties for a user account.

5.1.2 Different types of user accounts

A few different types of users exist. The type of a user is defined by a specific combination of properties. These are summed up below.

5.1.3 Hints for user names and passwords

Every user should have a unique userid on the system. Simply using a first name as userid clashes when there are two users with the same name within the school community. There are several strategies to construct unique names that are more or less easy to remember.

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

Because it is possible to configure every property independently from others, it can be difficult to figure out which combinations are necessary for granting a particular privilege. The table below provides an overview of a few common cases. Note that this table applies to both the web interface and the command line. The relevant command line switch is shown in parentheses.

Common combinations of properties for specific privileges.
privilege necessary properties
webmail access account must have a password (-P switch)
account must have webmail access (-I switch)
(optional) account may need 1 or more aliases (-E switch)
teleworking account must have a password (-P switch)
account must be a member of group 'teleworkers' (-G switch)
account must have a login shell (-s switch)
local system administration
(via web interface)
account must have a password (-P switch)
account must be a member of group 'janitors' (-G switch)
account must have a login shell (-s switch)
local system administration
(via command line)
account must have a password (-P switch)
account must be a member of group 'janitors' (-G switch)
account must have a login shell (-s switch)
account must have an 'advanced user' home directory (-d switch)
local system administration
(assigning shortcuts/icons)
account must have an SMB password (-W switch)
account must be a member of groups 'janitors' and 'programs' (-G switch)
local system administration
(all of the above)
account must have a password (-P switch)
account must have an SMB password (-W switch)
account must be a member of groups 'janitors' and 'programs' (-G switch)
account must have a login shell (-s switch)
account must have an 'advanced user' home directory (-d switch)

5.2 Adding a teacher account

You can add a teacher account either via the web interface or from the server's command line.

5.2.1 Adding a teacher account via the web interface

If you want to add a new account for a teacher you should take the following steps. In Janitor, navigate to: main menu | users and groups | add user. The following appears on the screen.

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.

[ adding a teacher account (part 1) ]
janitor_add_teacher1.png

[ adding a teacher account (part 2) ]
janitor_add_teacher2.png

Explanation:

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

[ success adding a teacher account ]
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

If you want to add a teacher account via the command line you have to be logged in your shell account on the server. You should issue the command illustrated below to add a user account 'bskinn'. Note that your input is emphasised in the illustration below.

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:

5.2.3 Status quo after adding teacher accounts

Here is the current status quo after adding users 'hparkh' and 'bskinn'.

[ status quo after adding two teacher accounts ]
janitor_add_teacher4.png

5.3 Adding a nest (grade) account

You can add a nest account either via the web interface or from the server's command line. This is basically the same procedure as adding a teacher account. A nest becomes a nest the moment at least 1 pupil is added to the nest. However, a nest-to-be needs 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.

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

If you want to add a new account for a nest (grade) you should take the following steps. In Janitor, navigate to: main menu | users and groups | add user. The following appears on the screen.

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.

[ adding a nest account (part 1) ]
janitor_add_nest1.png

[ adding a nest account (part 2) ]
janitor_add_nest2.png

Explanation:

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

[ success adding a nest account ]
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

If you want to add a nest (grade) account via the command line you have to be logged in your shell account on the server. You should issue the command illustrated below to add a user account 'grade3'. Note that your input is emphasised in the illustration below.

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:

NOTICE: There are many more options that could be specified. The important options are explained in section 5.2.2 Adding a teacher account via the command line above.

5.3.3 Status quo after adding nest (grade) accounts

Here is the current status quo after adding nests 'grade12' and 'grade3'. Note that these two accounts are considerd 'regular' users at this time. This is due to the fact that no pupils are assigned to these nests yet. After pupils have been added these accounts are transformed into real nests, see section 5.4.3 Status quo after adding single pupil accounts below.

[ status quo after adding two nest accounts ]
janitor_add_nest4.png

5.4 Adding a single pupil account

You can add a pupil account either via the web interface or from the server's command line. The procedure looks a lot like the one for adding a teacher or a nest account. The main difference is the account's primary group: a pupil account shares the same primary group with the corresponding nest 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

If you want to add a new account for a pupil you should take the following steps. In Janitor, navigate to: main menu | users and groups | add user. The following appears on the screen.

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.

[ adding a pupil account (part 1) ]
janitor_add_pupil1.png

[ adding a pupil account (part 2) ]
janitor_add_pupil2.png

Explanation:

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

[ success adding a pupil account ]
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

If you want to add a pupil account via the command line you have to be logged in your shell account on the server. You should issue the command illustrated below to add a user account 'catharina'. Note that your input is emphasised in the illustration below.

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:

NOTICE: There are many more options that could be specified. The important options are explained in section 5.2.2 Adding a teacher account via the command line above.

5.4.3 Status quo after adding single pupil accounts

Here is the current status quo after adding pupils 'may' and 'catharina' to nests 'grade12' and 'grade3' respectively. Note that these two nest accounts are now no longer considerd 'regular' users. This is due to the fact that pupils are now assigned to these nests. See also the previous status quo in section 5.3.3 Status quo after adding nest (grade) accounts above.

[ status quo after adding two pupils to two nest accounts ]
janitor_add_pupil4.png

5.5 Modifying a user account

You can modify the properties of a user account either via the web interface or from the server's command line. The procedure for nests, regular accounts and pupils are slightly different in the way the main edit screen is accessed. The command line procedure is the same for all types of accounts.

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

If you want to change the properties for a regular account (e.g. a teacher) you should take the following steps. In Janitor, navigate to: main menu | users and groups | modify users and groups | regular users. The following appears on the screen.

[ selecting a regular user account to modify ]
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.

[ selecting a nest or a pupil account to modify ]
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

Since the edit screens for regular users (teachers), nests (grades) and individual pupils are the same, only one example is given here. We use the teacher account 'hparkh' to illustrate the procedure. As you may recall, this account became a member of the secondary groups 'programs', 'teleworkers'. 'faculty' and 'staff' (see section 5.2.1 Adding a teacher account via the web interface above).

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.

[ adding two more workgroups to a regular user account ]
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.

[ success modifying a regular user account ]
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

The properties of a user account can also be changed using the command line. If you want to modify an acocunt, you have to be logged in your shell account on the server. You should issue the commands illustrated below to view and change the user account 'bskinn'. Note that your input is emphasised in the illustration below. In this example the goal is to add an e-mail alias 'coach' to the existing e-mail aliases associated with the account. After modifying the aliases e-mail addressed to burrhus.skinner@exemplum.serveratschool.net and also coach@exemplum.serveratschool.net will be delivered in the mailbox '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: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:

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

You can delete a user account either via the web interface or via the command line. Both variants are discussed in the examples below. The procedures for deleting regular users (teachers), pupils and nests (grades) are slightly different. See sections 5.6.1 Deleting a regular user account, 5.6.2 Deleting a pupil account and 5.6.3 Deleting a nest (grade) account respectively.

5.6.1 Deleting a regular user account

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

[ selecting a regular user account to delete ]
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.

[ confirming deletion of a regular user account ]
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.

[ status quo after deletion of a regular user account ]
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

A nest (grade) can only be deleted when all the pupils of that nest (grade) are moved to another nest (grade) or the pupil accounts are deleted alltogether.

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.

[ selecting a pupil account for deletion (step 1) ]
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.

[ selecting a pupil account for deletion (step 2) ]
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.

[ configming deletion of a pupil account ]
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.

[ success deleting  pupil account ]
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

If you want to delete a nest (grade) account you should take the following steps. First you need to remove all pupils associated with the nest you wish to delete. See section 5.6.2 Deleting a pupil account above if you need to delete the pupil accounts, see section 5.9 Promoting nests (grades) manually below if you merely want to move pupil accounts to another nest (grade).

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.

[ selecting a nest for deletion ]
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.

[ confirm deletion of nest ]
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.

[ status after deletion of nest ]
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

Janitor offers an option to create user accounts en masse by processing a specially crafted batch file. This option only works from the command line; there is no equivalent in the web interface.

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.

[ status quo before mass addition of teachers accounts ]
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

Before accounts can be created in bulk, an input file has to be created. Such a file consists of one or more lines of text, one for each account. The twelve individual fields defining an account are delimited with colons. Some of those fields (gecos, sgroups, aliases, ips) are in themselves comma delimited lists.

The format of this string is as follows:

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

Explanation:

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.

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

A more realistic batch file for the Exemplum Primary School, would be the file 'staff.in' as shown below.

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:

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

If you have created a file called 'staff.in', you can process this file using a single janitor command. In order to do this, you have to be logged in your account on the server. Your input is emphasised in the illustration below.

[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.

[ status quo of regular users after processing batch file ]
janitor_add_user_batch1.png

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

[ status quo of workgroups after processing batch file ]
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

Because it is a very tedious task to add many pupil accounts manually using the procedure described in section 5.4 Adding a single pupil account, a feature was added to Janitor to add pupil accounts using a combination of the web based interface and the command line. The procedure is as follows. NOTICE: In the examples below the ICT coordinator now enters the scene. Up to now the school's local systems administrator (Freddie Frinton, 'ffrint') has managed the user accounts and other systems administration tasks. However, now that the account for the ICT coordinator (Amelia Cackle, 'acackl') has been created in section 5.7 Adding multiple user accounts above, the ICT coordinator will be using the web interface of Janitor. The local systems administrator still performs the necessary tasks at the command line. You can see who is using the web interface by looking at the userid in the top-right corner of every screen in the web interface.

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).

Note that the exact format of the date of birth that is acceptable depends on the file format. For the fixed record length format the individual numbers (day, month and year) can be configured. For the comma delimited files there are three different variations: either 'yy-mm-dd', 'mm-dd-yy' or 'dd-mm-yy'. Note that the dashes '-' may be replaced by slashes '/' or dots '.' when specifying a date. Also, either 2-digit or 4-digit years are acceptable (but see the notice below).

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

If you want to upload a file with pupil's data in Janitor, you should navigate to: main menu | tools | upload pupil's data. A screen like the following appears.

[ upload dialogue ]
janitor_upload_pupils1.png

Explanation:

After selecting the correct file (here a file called '2005-2006.TXT), press [Upload]. The file will be uploaded and an overview of nests (grades) and pupils is displayed as shown in the next section. Note that this file '2005-2006.TXT' should be generated by the schools administration software. We use this particular name as a mere example.

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

After succesfully uploading the file a screen like the following appears.

[ after upload (part 1) ]
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.

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

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:

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

[ after upload (part 2) ]
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.

[ after editing all problematic lines ]
janitor_upload_pupils4.png

[ a generate button appears when everything looks good ]
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

After Janitor displays the message 'Everything looks OK', you should press the button [Generate]. The following then appears on the screen.

[ after generating the input it is shown on screen too ]
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

At this point the local systems administrator needs to proceed with actually adding the new accounts. This can be done by executing the file that was generated in the previous step ('/var/tmp/file20050831231325.sh'). This must be done using root privileges because the file that was prepared by the user interface is not readable by ordinary users, not even the members of the group 'janitors'. This is a security measure.

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.

[ status quo of nests after processing ]
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

Every year pupils and grades are rearranged: new pupils start in the first grade and the oldest pupils move on to another school. As a rule the remaining pupils are promoted to the next grade. This effect has to be reflected in the way the pupil accounts are connected to the nest (grade) accounts. This section discusses the way to promote nests of pupils manually. Section 5.10 Promoting nests (grades) via file upload presents a way to promote pupils 'en masse'.

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

There are several ways to deal with the accounts of the old 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.

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

If you want to promote a nest 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.

[ status quo of nests before promoting grade8 ]
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.

[ promoting grade8 to alumni ]
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.

[ status quo of nests after promoting grade8 ]
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

The procedure for promoting pupils at the command line is slightly different. If you want to promote pupils this way you have to be logged in your shell account on the server. You should issue the commands illustrated below to promote the user accounts 'andrew, 'branwell, 'edith, 'elisabeth2', 'henrietta', 'william1' and 'william3' (the old 'grade7') to 'grade8'.

[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

Because it is a very tedious task to promote all nests manually using the procedure described in section 5.9 Promoting nests (grades) manually, let alone promoting all individual pupils using by changing their primary group manually using the procedure described in section 5.5 Modifying a user account, a feature was added to Janitor to add and/or modify pupil accounts using a combination of the web based interface and the command line. This is the same tool as discussed in section 5.8 Adding multiple pupils via file upload above.

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 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

If you want to promote pupils by uploading a file with current pupil's data, you should take the following steps. In Janitor, navigate to: main menu | tools | upload pupil's data. A screen like the following appears. (This is the same screen as shown in section 5.8.2 Uploading the file with pupil's data above).

[ upload dialogue for new school year ]
janitor_promote_upload1.png

Explanation:

After selecting the correct file (here a file called '2006-2007.TXT), press [Upload]. The file will be uploaded and an overview of nests (grades) and pupils is displayed as shown in the next section. Note that this file '2006-2007.TXT' should be generated by the schools administration software. We use this particular name as a mere example.

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

After succesfully uploading the file a screen like the following appears.

[ tuning the upload for the new school year ]
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.

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

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:

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

Every time new pupils are entering the school there is a chance that name clashes occur. In the initial upload of pupil's data (see section 5.8.3 Preparing the pupil's data above) the problem with the two Mary's was resolved the following way. Now in the next school year 'mary' is being promoted to grade 7 and 'mary1' to grade 2 (even though she stays in the nest 'grade12' which combines the pupils in grades 1 and 2). The following problem occurs. Yet another Mary arrives at the Exemplum Primary School: Mary Kingsley. After uploading the new data, Janitor detects the problem illustrated in the image below.

[ oops ]
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.

[ oops ]
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.

[ oops ]
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.

[ comining grades 1 and 2 ]
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

After Janitor displays the message 'Everything looks OK', you should press the button [Generate]. The following then appears on the screen.

[ after generating (part 1) ]
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.

[ after generating (part 2) ]
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

At this point the local systems administrator needs to proceed with actually adding the new accounts adn updating the existing ones. This can be done by executing the file that was generated in the previous step ('/var/tmp/file20050906152456.sh'). This must be done using root privileges because the file that was prepared by the user interface is not readable by ordinary users, not even the members of the group 'janitors'. This is a security measure.

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

If you install the DAEMON Tools virtual CD player on your workstations (see chapter VI. DAEMON Tools virtual CD player) you need to have a way to create images of a complete CD. An easy way to create such .iso-files is to use the special Janitor feature. After you have created an .iso-file of a CD-ROM, you can store the CD-ROM in a safe place (maybe off the school premises) and use the image via DAEMON Tools. This section deals with creating the image files.

6.1 Creating .iso-files via the web interface

If you want to create an image (.iso-file) of a CD-ROM using the web interface you should take the following steps.

After placing the CD-ROM in the CD-ROM player, in Janitor navigate to: main menu | tools | cd-rom images. A screen like the following appears.

[ choosing the name for a CD-ROM image ]
janitor_cdrom_image1.png

Explanation:

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.

[ choosing the name for a CD-ROM image ]
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.

[ choosing the name for a CD-ROM image ]
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

You can also create a CD-ROM image using the command line. The procedure is illustrated below. Your input is emphasised. Note that you can use the command 'janitor cdimage' without additional parameters to monitor the status quo. Eventually the answer will be 'no background process is running'. This indicates that the process is complete.

[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

At this time there is no option to remove CD-ROM images via Janitor. If you want to remove the .iso-files you could remove them manually from the directory /home/share/iso. Alternatively you could simply delete the relevant file(s) from the R: drive from a Windows client. This works for members of the group 'janitors', e.g. the local systems administrator (Freddie Frinton) and also the ICT coordinator (Amelia Cackle).

(top)

7. Advanced topics

This section discusses some advanced Janitor configuration topics. It is mainly of interest for the local systems administrator. If your system is already properly configured, you can skip the remainder of this section without problem and proceed with section 8. Conclusion below.

7.1 Tweaking Janitor via janitor.conf

Janitor is built from two parts: a command line interface janitor(1) and on top of that a web based interface. Janitor's main configuration file is /etc/janitor/janitor.conf. This file has to be configured once by the (local) systems administrator. This is documented in section 10.1 The main Janitor configuration file in chapter V. Configuring all ServerAtSchool components in the ServerAtSchool Installation Guide.

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:

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

A second configuration file exists for the Janitor web interface. This configuration file (/home/httpd/janitor/config/config.php) contains all specific parameters for the web interface. These includes parameters for the file upload feature and definition of background colours and the like. The illustration below shows an example of the configuration file. Lines of interest are emphasised.

<?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:

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

Janitor is still work in progress, even though it is already very useful for complex tasks like maintaining user accounts on a ServerAtSchool server, many of which that need to be changed at least once every year. Comments and suggestions for improvement (or maybe even patches) are welcome at: janitor (at) berestijn (dot) nl.

(top)

Authors: Peter Fokker <peter (at) berestijn.nl> and Dirk Schouten <schoutdi (at) knoware.nl>
$Id: janitor.html,v 1.25 2006/03/31 08:16:19 peter Exp $