Added documentation for LDAP

Command-Line-Interface.md

@@ -17,5 +17,5 @@ Starting Calibre-Web with `-k "" -c ""`, deactivates the ssl-server, it falls ba
 
 Calibre-Web supports the following Environmental variables.
 
-CALIBRE_DBPATH allows to set the home directory for calibre-web's settings files (app.db. calibre-web.log, gdrive.db)\
+`CALIBRE_DBPATH` allows to set the home directory for calibre-web's settings files (`app.db`, `calibre-web.log`, `gdrive.db`)\
-CALIBRE_PORT allows to set the default listening port during creation of the settings database. Afterwards the port which is configured in the UI, is used.
+`CALIBRE_PORT` allows to set the default listening port during creation of the settings database. Afterwards the port which is configured in the UI, is used.

Configuration.md

@@ -38,7 +38,7 @@ Enable anonymous browsing:\
 Tick to allow not logged in users to browse the catalog, anonymous user permissions can be set as admin ("Guest" user)
 
 Enable uploading:\
-Tick to enable uploading of PDF, epub, FB2, TXT, Mobi, AZW, AZW3, HTML, RTF, ODT, DJVU, PRC, DOC, DOCX, CBR, CBZ, and CBT files. If imagemagick library is installed, covers can be extracted from some (PDF, epub, CBT, CBZ) of the uploaded file formats. If a language viewing restriction is applied while uploading the book, book language is automatically set to this language to allow the user to view the recently uploaded book.
+Tick to enable uploading of PDF, epub, FB2, TXT, Mobi, AZW, AZW3, HTML, RTF, ODT, DJVU, PRC, DOC, DOCX, MP3, M4A, M4B, CBR, CBZ, and CBT files. If imagemagick library is installed, covers can be extracted from some (PDF, epub, CBT, CBZ) of the uploaded file formats. If a language viewing restriction is applied while uploading the book, book language is automatically set to this language to allow the user to view the recently uploaded book.
 
 Enable remote login ("magic link"):\
 Tick to enable remote login, i.e. a link that allows user to log in via a different device.
@@ -181,7 +181,7 @@ Currently Calibre-Web supports two theme, the Standard ligh one, and the dark Ca
 
 Regular expression for ignoring columns and Link read/unread status to Calibre column:\
 If you having a bool custom column in Calibre you can use it as a "global" read/unread status (only usefull in single user environments) In this case you can select this column in the Link read status. After saving the Read/Unread selection on each book is read from this column and also saved to this field in the calibre-database. Furthermore you should Enter this column name to the "Regular expression for ignoring columns", so the column isn't showing up twice in Calibre-Web.\
-Example: ".\*" would exclude all custom columns, "Read" only the column with the name column, "^My\scol.\*" all Columns starting with "My col". **Remark**: The " given in the example are NOT belonging to the text you should enter.
+Example: `.\*` would exclude all custom columns, `Read` only the column with the name column, `^My\scol.\*` all Columns starting with `My col`.
 
 Regular expression for title sorting:\
 Calibre stores internally the title and a "sorted title". Title often starting with articles like "A" in english, or "Die/Der/Das" in german, which make no sense to sort after, therfore all of the listed words in these field are ignored for sorting the title. The default is taken from a german Calibre program. For french it should be something like "^(Le|La)\s"
@@ -196,17 +196,25 @@ How to use the feature?
 5. The field "Link read/unread status to Calibre column" should now offer a selection of all boolean custom columns of the corresponding Calibre library, select the appropriate entry and save
 The read/unread status is now identical in Calibre and Calibre-Web
 
-View Restrictions based on Calibre Column:\
+Visibility Restrictions based on Calibre Custom Column:\
-Sometimes you want to hide certain books from some users (like your kids). You can allow and deny the visibility of books based on the content of a Custom Column. Alternativly you can also use tags to allow and deny books. Both features can be used on a per user base. In this setting you define the Custom Column where the restriction shall be baed on. Lateron you can add all rules by editing the user settings. Furthermore you can define a default Visibilitys in the "Default Visibilitys for New Users" section. Admins can change their own visibility restirctions on their own user settings page.
+You can add restrictions based on Custom Columns if you want to hide certain books from some users (like your kids). In this setting you define the Custom Column where the restriction shall be based on. If you see None as only option, you have no text content Custom Columns in your Calibre Lib.
+The restrictions are on per user base, to change the restrictions of exisiting users, goto `edit user` and than you can edit the restrictions for this specific user.
+
 
 ### Default settings and visibilitys for new users
 
 The options selected in this section define the access rights and visibilitys new users having upon registering, and the default settings for newly created users by the admin (can be changed during initial creation, or later by admins).
 The visibilitys (except Visibility Restriction settings) can be changed by the users themselves later on. The Guest user (User for anonymous access) is an except from this, only admins can change the visibilities for the Guest user. 
 
+Visibility Restrictions based on Calibre Custom Column:\
+You can allow and deny the visibility of books based on the content of the Custom Colum selected by `View Restriction based on Calibre Custom Column` setting.  You can define a default Visibilitys in the `Default Visibilitys for New Users` section. Admins can change their own visibility restrictions on their own user settings page. You can restrict the visibility to only certain entries in this column (like user is only allowed to view books with entry "Kids") by allowing this Column entry, or exclude certain entries (like user is not allowed to view books with entry "Adult"). Allowing and dening content based on Custom Columns can be combined and can also be combined with restricts based on tags.
+
+Visibility Restrictions based on Tags:\
+You can allow and deny the visibility of books based on `tags`. You can define a default Visibilitys based on tags in the `Default Visibilitys for New Users` section. Admins can change their own visibility restrictions on their own user settings page. You can restrict the visibility to only certain tags (like user is only allowed to view books tagged as "kid") by allowing this tag, or exclude books with certain tags (like user is not allowed to view books with tag "Adult"). Allowing and dening content based on Custom Columns can be combined and can also be combined with restricts based on tags. 
+
 ### eBook Viewer and eBook Download
 
-The integrated eBook viewer is available for pdf, epub, txt and cbr, cbz and cbt files. The option is showing up if user has the right to "View Ebooks". If you are upgrading from older versions, it might be possible that the admin user lost the right to download or view books.
+The integrated eBook viewer is available for pdf, epub, txt and cbr, cbz and cbt files. The option is showing up if user has the right to `View Ebooks`. If you are upgrading from older versions, it might be possible that the admin user lost the right to download or view books.
 
 ### Using Goodreads integration
 

FAQ.md

@@ -20,7 +20,7 @@ All settings of Calibre-Web are stored in the app.db in the root folder of the p
 I have succesfully tested the following OPDS-Reader:
 - Chunky on iOS (mainly for comics)
 - Marvin and Marvin3 on iOS
-- Calibre-companion on Android (Book downloads viewing book details are also supported with this reader even it's not using the standard opds features). Download is only working with anonymous browsing enabled
+- Calibre-Companion on Android (Book downloads viewing book details are also supported with this reader even it's not using the standard opds features). Download is only working with anonymous browsing enabled
 - Kybook 1/2/3 on iOS
 - Megareader on iOS (download seems not to work)
 - moon+ on Android (Cover pictures are only displayed with anonymous browsing enabled, tested with v4.5.7)
@@ -106,15 +106,7 @@ Shelfs can be filled book by book on the corresponding detail page. Books can be
 In a one user use case you can use the guest account for sending ebooks to kindle. Please add in this case a kindle-email to the guest account, afterwards the "send to kindle" button appears for the guest user. If more than one user is accessing the guest account this is not working, as you can only have one kindle-email linked to a user.
 
 
-### Error on Startup: "the STRING opcode argument must be quoted"
+### Link Read Status to Calibre Custom Column
-
-If the calibre-web repro is cloned via git and certain git setting are set (line endings conversion), this could cause this error. The cause is that the line endings in the file cps/translations/iso639.pickle are converted to "windows" endings. To solve the problem, please replace the file with the version from:\
-`https://raw.githubusercontent.com/janeczku/calibre-web/master/cps/translations/iso639.pickle\`
-or\
-open the file with a advanced editor like notepad++ and change the line endings to Unix -> only LF.
-
-
-### Link Read Status to calibre custom column
 
 In a single user Calibre installation you can use a boolean custom column to keep track of your read and unread books. Calibre-web can do the following. You can link the Calibre status to the read/unread status in Calibre-Web. As mentioned above this only works in a SINGLE USER use-case. If you are having more than one user in Calibre-Web this will cause trouble, because the read/unread status is used for all users, so if one user ticks a book as read, all users will see this book as read. In a multiuser Calibre-Web use case it's absolutly manatory not to use this feature.\
 How to use the feature?
@@ -126,16 +118,16 @@ How to use the feature?
 The read/unread status is now identical in Calibre and Calibre-Web
  
 
-### How to handle Multiple calibre-libs
+### How to handle Multiple Calibre Libs
 
-The recommended way for handling mulitple libraries is to start multiple instances of calibre-web. Instead of having several copies of the calibre-web code, command line options can be used for this. First start calibre-web with the normal command:\
+The recommended way for handling multiple libraries is to start multiple instances of calibre-web. Instead of having several copies of the calibre-web code, command line options can be used for this. First start calibre-web with the normal command:\
 `python3 [path to calibre-web]/cps.py`\
 Configure the path to the metadata.db, set the logfile to a new filename (e.g. instance1.log) and change the port to e.g. 8084. Now stop calibre-web rename the newly generated app.db to e.g. instance1.db. Repeat this procedure for every instance you want to run. At the end start all instance with the commandline-parameter -p:
 ```
-nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web]instance1.db
+nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web instance1.db]
-nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web]instance2.db
+nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web instance2.db]
 ...
-nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web]instanceN.db
+nohup python3 [path to calibre-web]cps.py -p /[path to calibre-web instanceN.db]
 ```
 The command nohup puts the command to the background, so all instances can be started at once. Another option would be using several terminal windows. The final solution would be creating different service files for the different instances. All instances will be accessable afterwards with different port adresses like:\
 127.0.0.1:8084 for instance1, 127.0.0.1:8085 for instance2 and so on. This procedure can also be used for windows with the usual adoptions (command console/batch programm instead of terminal, task planer instead of service script).

LDAP.md

@@ -0,0 +1,158 @@
+## Installation
+
+LDAP can be used as login provider for Calibre-Web. As prerequiste you need to install the dependencies listed in optional-requirements.txt in the LDAP section. 
+
+## Configuration 
+
+After a reboot of Calibre-Web you should see Flask_SimpleLDAP in the about section and in the Admin section Basic Configuration, Feature Configuration a new option "Login Type" apears.
+After selecting it you have to configure your LDAP connection:
+LDAP Server Host: Please insert the same of your LDAP server, or it's IP Address, without starting ldap://\
+LDAP Server Port: Please insert your servers port here, usually 389 for unencrypted traffic, and 636 for ssl encrpyted traffic\
+LDAP Encryption: For STARTTls select `TLS`, for SSL encrypted connection use `SSL`\
+LDAP Certificate PATH: This field is only visible for TLS or SSL encrypted connections. If your server need a certificate for client authentication, enter the file path on the server\ 
+LDAP Administrator Username: Please fill in your administrators username, normally something like `cn=admin,dc=example,dc=com`\
+LDAP Administrator Password: Enter your Adminstrator's password, after submitting the form, the field will be empty as in the create user section\
+LDAP Distinguished Name: Put in your search root, usually something like dc=example,dc=com\
+LDAP User Object Filter: Put in the search term used to find a specific user. Usually something like `(&(objectclass=Person)(userPrincipalName=%s))`. The string has to contain exactly one `%s`, this is replace by Calibre-Web with the username is currently searchs for\
+LDAP Group Object Filter: Field can be empty if you want to add your users manually. Otherwise it should be filled with a search term to query the group to add, usually something like `(&(objectclass=groupofnames)(cn=%s))`. The string has to contain exactly one `%s`, this is replace by Calibre-Web with the groupname\ 
+LDAP Group Name: The group name to search for upon importing users from the LDAP server\
+LDAP Group Members Field: The field in the Response to the Group query, usually something like `member`, or `memberuid`
+
+If you enter a password in the edit user section for your admin account, you can login as fallback if the LDAP server is not reachable (or connection is wrong configured). Otherwise there is no chance to log into Calibre-Web and change  settings. If the ldap server is down no user without fallback password can log into Calibre-Web, user's passwords are not updates/stored in calibre-webs own database. 
+
+Usernames are not case sensitive, so username `user` is same as `uSeR`.
+
+In the admin section it' possible to import users from a certain group from your LDAP server. Upon import, the username and if existing the email are imported. If users having a second email in their account, this email is imported as Kindle Email. For imported users the settings for new users are applied. User rights can be changed after import like for any other user. The import function can be conducted later on again, already imported users are not affected from later imports.
+
+## Example
+
+This is an basic example generated on a Manjaro Linux 19.0 with openldap version 2.4.49-1.
+Remark the string between the `< >` are symbolising are random choosen passwart and have to be replaced with your own passwords. Furthermore it's requested to also hash the admins password, this was skipped here for make the example better understandable. 
+Basic slap.conf file:
+```
+include		/etc/openldap/schema/core.schema
+include 	/etc/openldap/schema/cosine.schema
+include 	/etc/openldap/schema/inetorgperson.schema
+
+pidfile		/run/openldap/slapd.pid
+argsfile	/run/openldap/slapd.args
+
+#######################################################################
+# MDB database definitions
+#######################################################################
+
+database	mdb
+maxsize		1073741824
+suffix		"dc=calibreweb,dc=com"
+rootdn		"cn=root,dc=calibreweb,dc=com"
+rootpw		<root-password>
+
+directory	/var/lib/openldap/openldap-data
+# Indices to maintain
+
+index   objectClass     eq
+index   uid             pres,eq
+
+access to attrs=userPassword
+	by self write
+	by anonymous auth
+	by dn.base="cn=root,dc=calibre,dc=com" write
+	by * none
+
+access to *
+	by self read
+	by dn.base="cn=root,dc=calibre,dc=com" write
+	by * read
+```
+
+Following file was used for basic configuration:
+
+```
+# calibre.com
+dn: dc=calibreweb,dc=com
+dc: Calibreweb
+o: Calibre Organization
+objectClass: dcObject
+objectClass: organization
+
+# root, calibreweb.com
+dn: cn=root,dc=calibreweb,dc=com
+cn: root
+description: LDAP administrator
+objectClass: organizationalRole
+objectClass: top
+roleOccupant: dc=calibreweb,dc=com
+
+# People, calibreweb.com
+dn: ou=People,dc=calibreweb,dc=com
+ou: People
+objectClass: top
+objectClass: organizationalUnit
+
+# User Joe
+dn: uid=joe,ou=People,dc=calibreweb,dc=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+uid: joe
+cn: Joe Smith
+sn: Smith
+userPassword: {SSHA}<joes-password>
+
+# User John
+dn: uid=john,ou=People,dc=calibreweb,dc=com
+objectClass: top
+objectClass: person
+objectClass: organizationalPerson
+objectClass: inetOrgPerson
+uid: john
+cn: John Doe
+sn: Doe
+userPassword: {SSHA}<johns-password>
+
+#Generic groups
+dn: ou=groups,dc=calibreweb,dc=com
+objectclass:organizationalunit
+ou: groups
+
+# create the cps entry
+dn: cn=cps,ou=groups,dc=calibreweb,dc=com
+objectclass: groupofnames
+cn: cps
+member: uid=joe,ou=People,dc=calibreweb,dc=com
+member: uid=john,ou=People,dc=calibreweb,dc=com
+```
+
+Alternatively the following would work for defining the groups:
+
+```
+dn: cn=cps,ou=groups,dc=calibreweb,dc=com
+objectClass: posixGroup
+cn: cps
+gidNumber: 5001
+memberUid: joe
+memberUid: John
+```
+
+Example command for searching after group and user (done similar by Calibre-Web) 
+
+`ldapsearch -H ldap://my-computer.com -D "cn=root,dc=calibre,dc=com" -w <root-passwort> -b 'dc=calibre,dc=com' '(&(objectclass=groupofnames)(cn=cps))' member`\
+`ldapsearch -H ldap://my-computer.com -D "cn=root,dc=calibre,dc=com" -w <root-passwort> -b 'dc=calibre,dc=com' '(uid=john)' *`
+
+Corresponding Calibre-Web settings
+
+LDAP Server Host: my-computer.com\
+LDAP Server Port: 389\
+LDAP Encryption: None\
+LDAP Administrator Username: cn=root,dc=calibre,dc=com\
+LDAP Administrator Password: <root-passwort>\
+LDAP Distinguished Name: dc=calibre,dc=com\
+LDAP User Object Filter: (uid=%s)\
+LDAP Group Object Filter: (&(objectclass=groupofnames)(cn=%s))\
+LDAP Group Name: cps\
+LDAP Group Members Field: member
+
+
+
+

Setup-Reverse-Proxy.md

@@ -2,9 +2,16 @@
 
 Reverse proxy configuration examples for apache, nginx and IIS (on Windows) to use Calibre-Web:
 
+### Login via Header from Upstream Authentication Source
+
+If your reverse proxy has some kind of authentication mechanism, you can configure Calibre-web to log users in based on headers received from the proxy. If using this feature, it's important that only the proxy is exposed to users, because if the Calibre-web instance is at all directly exposed to traffic, then a malicious user will be able to log in as any user that exists via simply setting a header.
+
+In the admin configuration, check the box marked `Allow Reverse Proxy Authentication`, and then fill in the text box that appears with the name of the header that will contain the username. If you pass a username that isn't present in the database, nothing will happen - the user must exist beforehand in order to login.
+
+
 ### nginx
 
-nginx configuration for a local server listening on port 8080, mapping Calibre-Web to /calibre:
+nginx configuration for a local server listening on port 8080, mapping Calibre-Web to `/calibre`:
 
 
 ```
@@ -29,9 +36,9 @@ proxy_redirect http://$host/ https://$host:12345/;
 
 ### Apache 2.4
 
-Apache 2.4 configuration for a local server listening on port 443, mapping Calibre-Web to /calibre-web:
+Apache 2.4 configuration for a local server listening on port 443, mapping Calibre-Web to `/calibre-web`:
 
-The following modules have to be activated: headers, proxy, proxy_http, rewrite.
+The following modules have to be activated: `headers`, `proxy`, `proxy_http`, `rewrite`.
 ```
 Listen 443
 
@@ -77,7 +84,7 @@ Add the server variable:
 ![server variable](images/iis_6.png)
 
 (The local is comming on it's own) with UNDERSCORE and excact Name:
-"HTTP_X-SCRIPT_NAME"
+`HTTP_X-SCRIPT_NAME`
 
 Then add Reverse Proxy Rules:
 
@@ -85,13 +92,13 @@ Then add Reverse Proxy Rules:
 
 ![proxy rules step2](images/iis_8.png)
 
-Add the ip address and port of your calibre-web instance: e.g. http://127.0.0.1:8083
+Add the ip address and port of your calibre-web instance: e.g. `http://127.0.0.1:8083`
 
 Change the rule afterwards:
 
 ![proxy rules step2](images/iis_9.png)
 
-Enter the folder you want to have calibre-web in (/calibre-web instead of ^might also works). End the name without a slash, otherwise a call to /calibre-web would go to nowhere. And Add the servervariable to the request and give it the same name as the folder above with starting slash (/calibre-web in my example, again without trailing slash)
+Enter the folder you want to have calibre-web in (`/calibre-web` instead of `^` might also works). End the name without a slash, otherwise a call to `/calibre-web` would go to nowhere. And Add the server variable to the request and give it the same name as the folder above with starting slash (`/calibre-web` in my example, again **without trailing slash**)
 
 ![proxy rules step2](images/iis_10.png)
 
@@ -106,8 +113,3 @@ My web.config file looks like this:
 
 The crossed out sections aren't needed, they are leftovers from my experiments.
 
-### Login via header from upstream authentication source
-
-If your reverse proxy has some kind of authentication mechanism, you can configure Calibre-web to log users in based on headers received from the proxy. If using this feature, it's important that only the proxy is exposed to users, because if the Calibre-web instance is at all directly exposed to traffic, then a malicious user will be able to log in as any user that exists via simply setting a header.
-
-In the admin configuration, check the box marked `Allow Reverse Proxy Authentication`, and then fill in the text box that appears with the name of the header that will contain the username. If you pass a username that isn't present in the database, nothing will happen - the user must exist beforehand in order to login.

Setup-Service-on-Linux.md

@@ -1,6 +1,6 @@
 ## Start Calibre-Web as service under Linux with systemd
 
-If you want to get Calibre-Web started automatically after reboot follow this instructions. Create a file "cps.service" as root in the folder /etc/systemd/system with the following content:
+If you want to get Calibre-Web started automatically after reboot follow this instructions. Create a file `cps.service` as root in the folder /etc/systemd/system with the following content:
 
 ```
 [Unit]
@@ -16,7 +16,7 @@ WorkingDirectory={/PATH/OF/CPS.PY without cps.py}
 WantedBy=multi-user.target
 ```
 
-Replace the elements in '{}' like User, ExecStart and WorkingDirectory with your username and file- and foldernames.
+Replace the elements in `{}` like User, ExecStart and WorkingDirectory with your username and file- and foldernames.
 
 `sudo systemctl enable cps.service`