viewvc.cgi/docman/admin.txt

Document Manager Administration manual


INSTALATION INSTRUCTIONS
------------------------

1. get latest version of Document Manager from
        http://www.rot13.org/~dpavlin/docman.html

2. go to installation directory (which doesn't have to be under your web
   server) and untar distribution

        cd /home/httpd/docman
        tar xvfz docman-*.tar.gz

   If you decide to install docman in some other directory, change
   $gblIncDir to that directory in docman.php!

3. go to directory which you want to have under Document Manager control
   (this directory needs to be accessable from your web server tree)

        cd /home/httpd/html

   chmod that directory so that web server can write in it.

        chown nobody /home/httpd/html

4. make a symlink from that directory to file which will be directory index

        ln -s /home/httpd/docman/docman.php /home/httpd/html/.index.php

5. add new DirectoryIndex entry to your apache configuration file. If your
   apache has config files in /etc/httpd/conf/httpd.conf find a line
   like

        DirectoryIndex index.html index.htm

   and add .index.php at the end.

        DirectoryIndex index.html index.htm .index.php

   It is important that new directory index file begins with dot -- that
   ensures that files won't be visible from Directory Manager interface.

6a. (if you don't want to users in SQL database) Go to you web server and
   check if you got autorization request. If you did, you also have
   .htusers in same directory in which is .index.php

   edit .htusers file to add users. You can do that by calling adduser.pl
   script. If you press just enter for password or enter auth_pop3
   docman will user e-mail address to connect to pop3 server and check
   password on it. For that e-mail address must be in following form:

        pop3login@pop3server.mydomain

   E-mail addresses are not used for anything else right now, so it's safe
   to enter invalid e-mail address it that's valid pop3 account. But, that
   WILL change, so you are warned!

6b. (alternative to 6a if your users are in SQL database) change $gblUsers
   in .docman.conf to $gblUsers = "htusers_sql";

   Download php-dbi class from http://pil.dk/downloads/dbi.tar.gz and
   untar it in docman's directory

        cd /home/html/docman
        tar xvfz dbi.tar.gz

   Construct SQL query which returns login, full name, password and
   email from your tables(s). If you don't have some of that data, replace
   them with literal strings.
   
        e.g. if your table is called my_users with columns who in which
             is login and column pw in which is plain text password you
             can use following query to get requested format:
                select who,'Auth user',pw,'nobody@com' from my_users

   Enter that SQL query under $dbi_sql in .docman.conf

   Construct $dbi in .docman.conf in following format:

        $dbi = "driver:database:user:password"

   driver can be: pgsql, mysql, oracle or odbc (as supported by php-dbi),
   database is name of database in which are your users and user/password
   is credentials for user which connects to database

6c. (alternative to 6b you want to authorize users based on IP numbers,
   client DNS names of HTTP Referarer header (URL from which they accessed
   docman site). Put $gblUsers = "htusers_header"; in .docman.conf use
   following form in your .htusers file:

   REMOTE_ADDR=10.0.0.3:Full name:auth_header:e-mail@foo.bar
   remote_hostname=myworkstation:Full name:auth_header:e-mail@foo.bar
   http_referer=test.foo.bar:Full name:auth_header:e-mail@foo.bar

   Please note that you *have to* put "auth_header" in password field
   and that valid options for left side of = in login field are:
   remote_addr, remote_hostname or http_referer.

6d. (if you want some combination of 6a, 6b and/or 6c) put in .docman.conf
   $gblUsers = "htusers_union" and uncomment which htusers auth modules
   you want to use and in which order

7. (optional) You can create file named .info.inc in /home/httpd/html
   directory for some kind of motd file. You can use html markup in it
   also!

8. (optional) Copy docman.conf into /home/httpd/html/.docman.conf and
   edit values which override default values in docman.php

9. if you want to upload files which are bigger than 2Mb increase
   upload_max_filesize to more than 2Mb in php.ini. If you still get
   errors on files bigger than 8Mb increase post_max_size also.

You are ready to go.


DIRECTORY AND FILE STRUCTURE
----------------------------

Breakout of files in /home/httpd/docman/:

docman.php      - main docman php file (to be installed as DirectoryIndex)

docman.conf     - configuration file which will be copied in document
                  root of site

auth_pop3.php   - authorization module ($gblIncDir in docman.php must point
                        to location of this file)

htusers_file.php - module for access to users in .htusers files
htusers_sql.php - module for access to users which are in SQL database

adduser.pl      - perl script for adding of users (you can also add users
                        manually by editing .htusers file)

docman.txt      - user documentation
admin.txt       - administrator's documentation

contrib/        - directory with optional usefull scripts

dbi/            - optional directory for dbi classes is users are stored
                  in SQL database, it will be created after unpacking of
                  http://pil.dk/downloads/dbi.tar.gz

Breakout of files in /home/httpd/html/ (root directory of site under docman
management):

.changelog      - changes of files under docman management
.htusers        - file with users
.info.inc       - file with MOTD which is included in interface
.docman.conf    - configuration file for this site

Files in each directory under docman management (some of them may be missing,
they will be created automatically):

.bak/           - directory for backup copies of files
.del/           - directory with deleted files
.lock/          - directory with lock informations
.log/           - directory with changelogs for each file
.note/          - directory with notes for files


MISC
----

You can use document manager behind secure http server (https) simply by
installing it. For information take a look at http://www.modssl.org

1	dpavlin	1.1	Document Manager Administration manual
2
3
4			INSTALATION INSTRUCTIONS
5			------------------------
6
7			1. get latest version of Document Manager from
8			http://www.rot13.org/~dpavlin/docman.html
9
10			2. go to installation directory (which doesn't have to be under your web
11			server) and untar distribution
12
13			cd /home/httpd/docman
14			tar xvfz docman-*.tar.gz
15
16			If you decide to install docman in some other directory, change
17			$gblIncDir to that directory in docman.php!
18
19			3. go to directory which you want to have under Document Manager control
20			(this directory needs to be accessable from your web server tree)
21
22			cd /home/httpd/html
23
24			chmod that directory so that web server can write in it.
25
26			chown nobody /home/httpd/html
27
28			4. make a symlink from that directory to file which will be directory index
29
30			ln -s /home/httpd/docman/docman.php /home/httpd/html/.index.php
31
32			5. add new DirectoryIndex entry to your apache configuration file. If your
33			apache has config files in /etc/httpd/conf/httpd.conf find a line
34			like
35
36			DirectoryIndex index.html index.htm
37
38			and add .index.php at the end.
39
40			DirectoryIndex index.html index.htm .index.php
41
42			It is important that new directory index file begins with dot -- that
43			ensures that files won't be visible from Directory Manager interface.
44
45	dpavlin	1.5	6a. (if you don't want to users in SQL database) Go to you web server and
46	dpavlin	1.4	check if you got autorization request. If you did, you also have
47			.htusers in same directory in which is .index.php
48	dpavlin	1.1
49	dpavlin	1.4	edit .htusers file to add users. You can do that by calling adduser.pl
50	dpavlin	1.1	script. If you press just enter for password or enter auth_pop3
51			docman will user e-mail address to connect to pop3 server and check
52			password on it. For that e-mail address must be in following form:
53
54			pop3login@pop3server.mydomain
55
56			E-mail addresses are not used for anything else right now, so it's safe
57			to enter invalid e-mail address it that's valid pop3 account. But, that
58			WILL change, so you are warned!
59
60	dpavlin	1.5	6b. (alternative to 6a if your users are in SQL database) change $gblUsers
61	dpavlin	1.4	in .docman.conf to $gblUsers = "htusers_sql";
62
63			Download php-dbi class from http://pil.dk/downloads/dbi.tar.gz and
64			untar it in docman's directory
65
66			cd /home/html/docman
67			tar xvfz dbi.tar.gz
68
69			Construct SQL query which returns login, full name, password and
70			email from your tables(s). If you don't have some of that data, replace
71			them with literal strings.
72
73			e.g. if your table is called my_users with columns who in which
74			is login and column pw in which is plain text password you
75			can use following query to get requested format:
76			select who,'Auth user',pw,'nobody@com' from my_users
77
78			Enter that SQL query under $dbi_sql in .docman.conf
79
80			Construct $dbi in .docman.conf in following format:
81
82			$dbi = "driver:database:user:password"
83
84			driver can be: pgsql, mysql, oracle or odbc (as supported by php-dbi),
85			database is name of database in which are your users and user/password
86			is credentials for user which connects to database
87
88	dpavlin	1.5	6c. (alternative to 6b you want to authorize users based on IP numbers,
89			client DNS names of HTTP Referarer header (URL from which they accessed
90			docman site). Put $gblUsers = "htusers_header"; in .docman.conf use
91			following form in your .htusers file:
92
93			REMOTE_ADDR=10.0.0.3:Full name:auth_header:e-mail@foo.bar
94			remote_hostname=myworkstation:Full name:auth_header:e-mail@foo.bar
95			http_referer=test.foo.bar:Full name:auth_header:e-mail@foo.bar
96
97			Please note that you have to put "auth_header" in password field
98			and that valid options for left side of = in login field are:
99			remote_addr, remote_hostname or http_referer.
100
101			6d. (if you want some combination of 6a, 6b and/or 6c) put in .docman.conf
102			$gblUsers = "htusers_union" and uncomment which htusers auth modules
103			you want to use and in which order
104
105			7. (optional) You can create file named .info.inc in /home/httpd/html
106	dpavlin	1.1	directory for some kind of motd file. You can use html markup in it
107			also!
108
109	dpavlin	1.5	8. (optional) Copy docman.conf into /home/httpd/html/.docman.conf and
110	dpavlin	1.3	edit values which override default values in docman.php
111
112	dpavlin	1.5	9. if you want to upload files which are bigger than 2Mb increase
113	dpavlin	1.2	upload_max_filesize to more than 2Mb in php.ini. If you still get
114			errors on files bigger than 8Mb increase post_max_size also.
115
116	dpavlin	1.3	You are ready to go.
117	dpavlin	1.1
118
119			DIRECTORY AND FILE STRUCTURE
120			----------------------------
121
122			Breakout of files in /home/httpd/docman/:
123
124			docman.php - main docman php file (to be installed as DirectoryIndex)
125	dpavlin	1.4
126			docman.conf - configuration file which will be copied in document
127			root of site
128
129	dpavlin	1.1	auth_pop3.php - authorization module ($gblIncDir in docman.php must point
130			to location of this file)
131
132	dpavlin	1.4	htusers_file.php - module for access to users in .htusers files
133			htusers_sql.php - module for access to users which are in SQL database
134
135	dpavlin	1.1	adduser.pl - perl script for adding of users (you can also add users
136			manually by editing .htusers file)
137
138			docman.txt - user documentation
139			admin.txt - administrator's documentation
140
141	dpavlin	1.4	contrib/ - directory with optional usefull scripts
142
143			dbi/ - optional directory for dbi classes is users are stored
144			in SQL database, it will be created after unpacking of
145			http://pil.dk/downloads/dbi.tar.gz
146
147			Breakout of files in /home/httpd/html/ (root directory of site under docman
148			management):
149	dpavlin	1.1
150			.changelog - changes of files under docman management
151			.htusers - file with users
152			.info.inc - file with MOTD which is included in interface
153	dpavlin	1.4	.docman.conf - configuration file for this site
154	dpavlin	1.1
155			Files in each directory under docman management (some of them may be missing,
156			they will be created automatically):
157
158			.bak/ - directory for backup copies of files
159			.del/ - directory with deleted files
160			.lock/ - directory with lock informations
161			.log/ - directory with changelogs for each file
162			.note/ - directory with notes for files
163
164
165			MISC
166			----
167
168			You can use document manager behind secure http server (https) simply by
169			installing it. For information take a look at http://www.modssl.org
170