Security¶
Access restriction: DocFetcher Server allows restricting access to the User Area and/or Admin Area via a login page. If you are setting up DocFetcher Server to be accessed over the internet, this login page is something you should strongly consider turning on, since for example malicious parties with access to the User Area could easily find and retrieve most or all of your indexed files using a simple * catch-all wildcard query. If you turn on the login page, you should also turn off HTTP and use HTTPS only, as with HTTP your login credentials would be sent unencrypted to the server. And if you use HTTPS, use it with a “real” SSL certificate, not the self-signed one that ships with DocFetcher Server, as the latter certificate is shared among DocFetcher Server users and thus offers practically zero protection.
The Access tab: The relevant sections in the Admin Area for configuring access restriction are the Users section and the Security Implications section on the Access tab. The Users section is where you define users, and the Security Implications section provides some feedback about how your user definitions affect server security.
Creating new users: How DocFetcher Server’s security model works may not be entirely obvious at first, and it may be easier to understand with a concrete example, so let’s create some dummy users. To this end, click the Add... button under the Users table to open the Add User dialog. This is where you can create a new user. Now create two users, one named “admin” and with the “Admin” checkbox on the Add User dialog ticked, and the other named “user” and without the “Admin” checkbox ticked. (Side note: When you use DocFetcher Server for real, it would be better not to have a user named “admin”, since the latter is a common username and would make you more vulnerable to brute-force attacks on the login page.) After creating the first user, you will see a warning in the Security Implications section about the server needing to be restarted, so restart the server after having created the two users, and restart the browser too while you’re at it.
Logging in: Upon revisiting the web interface you will see a login page. If you log in as the newly created “admin” user, you will be able to enter the Admin Area. If you log in as the “user” user, there will be no link to the Admin Area, and trying to be clever by appending “/admin/” to the website URL won’t work because you’ll then just get an error page. Now, log in as the “admin” user, because we want to go back to the Admin Area.
Toggling admin rights: In the Admin Area, go to the Access tab and have another look at the Users table. By clicking the cells in the Admin column, you turn admin rights for a particular user on and off. Having admin rights just means being able to access the Admin Area, in addition to the User Area, whereas not having admin rights means being able to access only the User Area.
Checkbox enabled state: While turning the admin rights of the two dummy users “admin” and “user” on and off, you may notice that the checkbox Allow access to the user area without login below the Users table switches between being enabled and being disabled (not to be confused with being ticked and not being ticked). The pattern is that the checkbox is enabled when both users have admin rights, or both users don’t have admin rights. When one user has admin rights and the other doesn’t, the checkbox is disabled. To understand why DocFetcher Server works that way, a proper understanding of its security model is needed.
Three security levels: First of all, there’s the basic fact that the web interface is divided into a User Area and an Admin Area. This gives rise to the three security levels supported by the application:
Level 0: Neither User Area nor Admin Area are login-protected. That means no login is needed to access either area.
Level 1: Only the Admin Area is login-protected. The User Area can be accessed without login.
Level 2: Both the User Area and the Admin Area are login-protected.
The security level isn’t something you can set directly, but is instead determined by what users are defined in the Users table and whether the checkbox Allow access to the user area without login is ticked or not. The following table shows all possible cases and the resulting security levels:
Users defined in Users table |
Anonymous access to User Area? |
Security level |
|---|---|---|
None |
N/A |
0 |
One or more users, all are admins |
Yes |
1 |
One or more users, all are admins |
No |
2 |
One or more users, all are non-admins |
Yes |
1 |
One or more users, all are non-admins |
No |
2 |
Two or more users, some are admins and some are non-admins |
N/A |
2 |
To be clear, there’s no deeper significance to the numbers 0, 1 and 2, they are just labels and could be replaced by X, Y and Z. And the security level as such doesn’t actually “do” anything in the application, it’s just a shorthand for stating that under certain conditions the User Area and/or Admin Area will be login-protected or not login-protected.
When the checkbox is disabled: There are two N/As in the table above. In those cases, the Allow access to the user area without login checkbox remains disabled. The first N/A is because if you don’t define any users, then nobody could possibly log in, so there can be no login protection and all access must be by anonymous users. The second N/A is because it doesn’t make sense to define some users who can only access the User Area and at the same time allow anonymous access to the User Area.
Last case: The security levels can be somewhat tricky to reason about, but ultimately follow from common sense. For example, in the last case, if there are both admin and non-admin users, then it wouldn’t make sense to allow anonymous access to the User Area on top of that, which rules out security level 0 and 1, leaving only security level 2.
Case 4 and 5: Something about the table that requires an extra dose of common sense is case 4 and 5, where there are one or more users, who are all non-admins. If these two cases were implemented naively, then nobody would be able to enter the Admin Area in the two cases, because nobody would have the required admin rights to do so. But making the Admin Area completely inaccessible makes no sense (who’s going to create and maintain indexes?), so the cases 4 and 5 are treated as equivalent to the cases 2 and 3. In other words, no users having admin rights is treated as equivalent to all users having admin rights.
Jumping between cases: Returning to the dummy users example further above, it should now be clear – or at least comprehensible with some mental effort – why the checkbox is sometimes enabled and sometimes disabled: By turning admin rights for the various defined users on and off, we jump between the last case in the table and the four preceding cases, and this causes the checkbox to toggle between disabled and enabled.
But what does all this mean? Fine, so there are security levels and stuff, but what does all this mean in practice? To put it simply, you need to ask yourself two questions: First, do I want the User Area to be login-protected or not? Second, do I want the Admin Area to be login-protected or not? These two yes-no questions determine the security level for your server, and knowing the security level, you can refer to the table above to see how you need to define users and whether you need to tick the Allow access to the user area without login checkbox in order to get the desired security level.
The users.txt file: All users in the Users table and the state of the checkbox Allow access to the user area without login are stored in the file conf/users.txt. This file needs to be guarded well and have the right file permissions. Ideally, you’d want this file to be readable and writable only by root users and the user account under which DocFetcher Server is run. Others should have neither read nor write access.
Batch creation of users: Defining multiple or many users all at once can be done by editing the users.txt file. Please see the documentation in the users.txt file for details. Before editing, be sure to stop the server, so that the latter won’t overwrite your changes. Also, note that logged-in users can change their own passwords on the Preferences page in the User Area, so you could edit the users.txt file to batch-create a number of users with a shared initial password, and then let the users customize their passwords.
