Context Navigation

← Previous Changeset
Next Changeset →

Changeset 3116

Timestamp:

12/03/06 12:26:33 (18 years ago)

Author:

jerome

Message:

Improved the documentation.

Location:

pykota/trunk/docs

Files:

: 2 modified

installation.sgml (modified) (1 diff)
introduction.sgml (modified) (3 diffs)

Legend:

: Unmodified
: Added
: Removed

pykota/trunk/docs/installation.sgml

r3115	r3116
55	55	</para>
56	56
57		<para>
58		Now we will see what has to be done on each of the servers we are planning to use.
59		<note>
60		<title>Note</title>
61		<para>
62		Of course, depending on the size of your network, you may very well
63		use the same machine as both a Print Server and a database server.
64		This is especially the case if you've got only one server.
65		</para>
66		</note>
67		</para>
	57	<sect1>
	58	<title>Interactive step-by-step installation of PyKota with pksetup</title>
	59
	60	<para>
	61	<command>pksetup</command> is a command line tool with which you'll be able
	62	to install <application>PyKota</application> and all its dependencies in
	63	a completely interactive way. At the end of the installation, a shell
	64	script is created which allows you to replicate the very same
	65	installation in an automated way. This can be useful if you've got
	66	several servers to install identically.
	67	</para>
	68
	69	<para>
	70	Currently, <command>pksetup</command> is experimental, and only works
	71	with <ulink url="http://www.debian.org">Debian</ulink> and
	72	<ulink url="http://www.ubuntu.com">Ubuntu</ulink> distributions.
	73	In addition, the database backend which will be installed with
	74	this command is <ulink url="http://www.postgresql.org">PostgreSQL</ulink>
	75	and you have no choice for another backend. If you want another
	76	database backend, or use a different distribution, or want to do
	77	the installation manually, then read and follow the instructions in the next section.
	78	</para>
	79
	80	<para>
	81	To launch the installation procedure, just type <literal>pksetup</literal>
	82	followed with the name of your distribution, like :
	83	<screen>
	84	jerome@nordine:~$ pksetup debian
	85	</screen>
	86	and then follow the instructions and answer to the several questions you'll
	87	be asked.
	88	</para>
	89	</sect1>
68	90
69	91	<sect1>
70		<title>Database server installation</title>
71
	92	<title>Manual installation</title>
72	93	<para>
73		Depending on <application>PyKota</application>'s version number, different
74		types of storage backends may be supported, so we will see for each one of
75		them how to configure it.
	94	To do a manual installation, we will see what has to be done on each of the servers we are planning to use.
	95	<note>
	96	<title>Note</title>
	97	<para>
	98	Of course, depending on the size of your network, you may very well
	99	use the same machine as both a Print Server and a database server.
	100	This is especially the case if you've got only one server.
	101	</para>
	102	</note>
76	103	</para>
77	104
78	105	<sect2>
79		<title>PostgreSQL</title>
80
81		<para>
82		<application>PostgreSQL</application> is an <firstterm>Object Relationnal DataBase
83		Management System</firstterm> distributed under a <firstterm>Free Software</firstterm>
84		license from the
85		<ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink>
86		web site. It certainely is the free <acronym>RDBMS</acronym> which has the most advanced
87		features, and is widely used all over the world.
88		</para>
89
90		<para>
91		To configure your database, you must have PostgreSQL already working.
92		The complete installation of <application>PostgreSQL</application> is not covered by
93		the present manual, please refer to your system's documentation or to
94		<ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink> for
95		details.
96		</para>
97
98		<para>
99		One thing you have to check, though, is that every Print Server on which you
100		want to install the print quota mechanism, must be able to connect to the
101		<application>PostgreSQL</application> server. In the default installation of
102		<application>PostgreSQL</application> this may not be the case for security reasons, except if both
103		servers are in fact the same machine. In any case, it is recommended that you
104		check the <filename>/etc/postgresql/pg_hba.conf</filename> file and modify it if
105		needed. This file is self documented and its modification is straightforward.
106		You also have to make sure that <application>PostgreSQL</application> accepts <acronym>TCP/IP</acronym> connections.
107		To do so you either have to launch it with the <option>-i</option> option or
108		modify the <filename>/etc/postgresql/postgresql.conf</filename> file, which is
109		self documented and easy to modify too. Allowing <acronym>TCP/IP</acronym> connections
110		is not necessary though if your print quota database server and your Print Server are
111		the very same host.
112		</para>
113
114		<para>
115		Here's an excerpt from a <filename>pg_hba.conf</filename> file. This one rejects all
116		connections to PyKota's database excepted when made from the same host by <application>PostgreSQL</application> users
117		<literal>pykotauser</literal> or <literal>pykotaadmin</literal> with the correct password.
118		<screen>
119		local all postgres ident sameuser
120		local all all reject
121		host pykota pykotauser 127.0.0.1 255.255.255.255 crypt
122		host pykota pykotaadmin 127.0.0.1 255.255.255.255 crypt
123		host pykota all 127.0.0.1 255.255.255.255 reject
124		</screen>
125		</para>
126
127		<para>
128		Of course if your print server and your database servers have different <acronym>IP</acronym>
129		addresses, you have to replace the <literal>127.0.0.1</literal> address above with your print
130		server's <acronym>IP</acronym> address. As an alternative, you could still keep these
131		lines and add similar lines with other <acronym>IP</acronym> addresses if you have several
132		print servers for which you want a single centralized database.
133		<tip>
134		<title>Tip</title>
135		<para>
136		Don't forget to restart <application>PostgreSQL</application> if you modify
137		any of its configuration files, in order for the changes to take effect.
138		</para>
139		</tip>
140		</para>
141
142		<para>
143		Be careful, you may be unable to connect from a Print Server to the <application>PostgreSQL</application>
144		server even if the configuration is correct. Sometimes your connections may be blocked by
145		one or more network firewalls along the route from one machine to the other. If this
146		is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm>
147		to not filter the IP port used by <application>PostgreSQL</application>, which is
148		usually port <literal>5432/tcp</literal>.
149		<note>
150		<title>Note</title>
151		<para>
152		The TCP/IP network port used by PostgreSQL may be different. When in doubt, ask your
153		<firstterm>System Administrator</firstterm> for the correct value.
154		</para>
155		</note>
156		</para>
157
158		<para>
159		Now that your <application>PostgreSQL</application> server is up and running, and
160		is waiting for your connections, you have to create the print quota database.
161		To do so, you'll have to feed <application>PostgreSQL</application> with the
162		<filename>pykota-1.25_official/initscripts/postgresql/pykota-postgresql.sql</filename> file.
163		This file will create a print quota database administrator in the <application>PostgreSQL</application> system, then create an empty
164		print quota database and set some permissions on it. The print quota database administrator
165		is the <application>PostgreSQL</application>'s user used to manage the quota database.
166		The print quota database Administrator is not present in the quota database
167		itself, he is only defined in <application>PostgreSQL</application> and don't
168		have to exist on any system, nor in the print quota database. His default name
169		is <literal>pykotaadmin</literal>.
170		A print quota database read-only user is also created under the name of <literal>pykotauser</literal>.
171		This read-only user is used by <application>PyKota</application> to connect to the
172		print quota database when an user who is not a <application>PyKota</application> administrator
173		<footnote><para>a <application>PyKota</application> administrator is an user who can read the <filename>~pykota/pykotadmin.conf</filename> file.</para></footnote>
174		launches a pykota command. This prevents normal
175		users from being able to modify their own, or other users', quota information.
176		The database which will be created will be named <literal>pykota</literal> by default.
177		The <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users by
178		default respectively have <literal>readwritepw</literal> and <literal>readonlypw</literal>
179		as their passwords.
180		<note>
181		<title>Note</title>
182		<para>
183		You can choose other names and passwords if you want by modifying the
184		<filename>initscripts/postgresql/pykota-postgresql.sql</filename> file
185		accordingly, and report your changes into <application>PyKota</application>'s
186		configuration files.
187		</para>
188		</note>
189		</para>
190
191		<para>
192		To run this script, you can use the <command>psql</command> frontend to
193		<application>PostgreSQL</application>, but your priviledges must be sufficient
194		to be allowed to create users and databases. You can launch <command>psql</command>
195		as the <literal>postgres</literal> user which is <application>PostgreSQL</application>'s
196		default administrator, and connect to the default database named <literal>template1</literal>.
197		From a command line interpreter (i.e. shell), type the following commands :
	106	<title>Database server installation</title>
	107
	108	<para>
	109	Depending on <application>PyKota</application>'s version number, different
	110	types of storage backends may be supported, so we will see for each one of
	111	them how to configure it.
	112	</para>
	113
	114	<sect3>
	115	<title>PostgreSQL</title>
	116
	117	<para>
	118	<application>PostgreSQL</application> is an <firstterm>Object Relationnal DataBase
	119	Management System</firstterm> distributed under a <firstterm>Free Software</firstterm>
	120	license from the
	121	<ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink>
	122	web site. It certainely is the free <acronym>RDBMS</acronym> which has the most advanced
	123	features, and is widely used all over the world.
	124	</para>
	125
	126	<para>
	127	To configure your database, you must have PostgreSQL already working.
	128	The complete installation of <application>PostgreSQL</application> is not covered by
	129	the present manual, please refer to your system's documentation or to
	130	<ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink> for
	131	details.
	132	</para>
	133
	134	<para>
	135	One thing you have to check, though, is that every Print Server on which you
	136	want to install the print quota mechanism, must be able to connect to the
	137	<application>PostgreSQL</application> server. In the default installation of
	138	<application>PostgreSQL</application> this may not be the case for security reasons, except if both
	139	servers are in fact the same machine. In any case, it is recommended that you
	140	check the <filename>/etc/postgresql/pg_hba.conf</filename> file and modify it if
	141	needed. This file is self documented and its modification is straightforward.
	142	You also have to make sure that <application>PostgreSQL</application> accepts <acronym>TCP/IP</acronym> connections.
	143	To do so you either have to launch it with the <option>-i</option> option or
	144	modify the <filename>/etc/postgresql/postgresql.conf</filename> file, which is
	145	self documented and easy to modify too. Allowing <acronym>TCP/IP</acronym> connections
	146	is not necessary though if your print quota database server and your Print Server are
	147	the very same host.
	148	</para>
	149
	150	<para>
	151	Here's an excerpt from a <filename>pg_hba.conf</filename> file. This one rejects all
	152	connections to PyKota's database excepted when made from the same host by <application>PostgreSQL</application> users
	153	<literal>pykotauser</literal> or <literal>pykotaadmin</literal> with the correct password.
	154	<screen>
	155	local all postgres ident sameuser
	156	local all all reject
	157	host pykota pykotauser 127.0.0.1 255.255.255.255 crypt
	158	host pykota pykotaadmin 127.0.0.1 255.255.255.255 crypt
	159	host pykota all 127.0.0.1 255.255.255.255 reject
	160	</screen>
	161	</para>
	162
	163	<para>
	164	Of course if your print server and your database servers have different <acronym>IP</acronym>
	165	addresses, you have to replace the <literal>127.0.0.1</literal> address above with your print
	166	server's <acronym>IP</acronym> address. As an alternative, you could still keep these
	167	lines and add similar lines with other <acronym>IP</acronym> addresses if you have several
	168	print servers for which you want a single centralized database.
	169	<tip>
	170	<title>Tip</title>
	171	<para>
	172	Don't forget to restart <application>PostgreSQL</application> if you modify
	173	any of its configuration files, in order for the changes to take effect.
	174	</para>
	175	</tip>
	176	</para>
	177
	178	<para>
	179	Be careful, you may be unable to connect from a Print Server to the <application>PostgreSQL</application>
	180	server even if the configuration is correct. Sometimes your connections may be blocked by
	181	one or more network firewalls along the route from one machine to the other. If this
	182	is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm>
	183	to not filter the IP port used by <application>PostgreSQL</application>, which is
	184	usually port <literal>5432/tcp</literal>.
	185	<note>
	186	<title>Note</title>
	187	<para>
	188	The TCP/IP network port used by PostgreSQL may be different. When in doubt, ask your
	189	<firstterm>System Administrator</firstterm> for the correct value.
	190	</para>
	191	</note>
	192	</para>
	193
	194	<para>
	195	Now that your <application>PostgreSQL</application> server is up and running, and
	196	is waiting for your connections, you have to create the print quota database.
	197	To do so, you'll have to feed <application>PostgreSQL</application> with the
	198	<filename>pykota-1.25_official/initscripts/postgresql/pykota-postgresql.sql</filename> file.
	199	This file will create a print quota database administrator in the <application>PostgreSQL</application> system, then create an empty
	200	print quota database and set some permissions on it. The print quota database administrator
	201	is the <application>PostgreSQL</application>'s user used to manage the quota database.
	202	The print quota database Administrator is not present in the quota database
	203	itself, he is only defined in <application>PostgreSQL</application> and don't
	204	have to exist on any system, nor in the print quota database. His default name
	205	is <literal>pykotaadmin</literal>.
	206	A print quota database read-only user is also created under the name of <literal>pykotauser</literal>.
	207	This read-only user is used by <application>PyKota</application> to connect to the
	208	print quota database when an user who is not a <application>PyKota</application> administrator
	209	<footnote><para>a <application>PyKota</application> administrator is an user who can read the <filename>~pykota/pykotadmin.conf</filename> file.</para></footnote>
	210	launches a pykota command. This prevents normal
	211	users from being able to modify their own, or other users', quota information.
	212	The database which will be created will be named <literal>pykota</literal> by default.
	213	The <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users by
	214	default respectively have <literal>readwritepw</literal> and <literal>readonlypw</literal>
	215	as their passwords.
	216	<note>
	217	<title>Note</title>
	218	<para>
	219	You can choose other names and passwords if you want by modifying the
	220	<filename>initscripts/postgresql/pykota-postgresql.sql</filename> file
	221	accordingly, and report your changes into <application>PyKota</application>'s
	222	configuration files.
	223	</para>
	224	</note>
	225	</para>
	226
	227	<para>
	228	To run this script, you can use the <command>psql</command> frontend to
	229	<application>PostgreSQL</application>, but your priviledges must be sufficient
	230	to be allowed to create users and databases. You can launch <command>psql</command>
	231	as the <literal>postgres</literal> user which is <application>PostgreSQL</application>'s
	232	default administrator, and connect to the default database named <literal>template1</literal>.
	233	From a command line interpreter (i.e. shell), type the following commands :
	234	<screen>
	235	jerome@nordine:~$ cd pykota-1.25_official/initscripts/postgresql
	236	jerome@nordine:~/pykota-1.25_official/initscripts$ psql -h localhost -U postgres template1
	237	Welcome to psql, the PostgreSQL interactive terminal.
	238
	239	Type: \copyright for distribution terms
	240	\h for help with SQL commands
	241	\? for help on internal slash commands
	242	\g or terminate with semicolon to execute query
	243	\q to quit
	244
	245	template1=# \i pykota-postgresql.sql
	246	... a lot of output lines
	247	pykota=#
	248	</screen>
	249	<note>
	250	<title>Note</title>
	251	<para>
	252	If you use RPM or DEB packages, usually the
	253	<filename>pykota-postgresql.sql</filename> file gets installed into the
	254	<filename>/usr/share/pykota/postgresql</filename> directory, along
	255	with a README file.
	256	</para>
	257	</note>
	258	</para>
	259
	260	<para>
	261	If you want to you can change passwords later in
	262	<application>PostgreSQL</application> for the
	263	<literal>pykotaadmin</literal> and <literal>pykotauser</literal> users.
	264	To do so, just type the following lines while still being at the <command>psql</command>
	265	prompt (replace the password values by your own :
	266	<screen>
	267	pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword';
	268	ALTER USER
	269	pykota=# ALTER USER pykotauser PASSWORD 'anotherpassword';
	270	pykota=# \q
	271	jerome@nordine:~/pykota-1.25_official/initscripts/postgresql$
	272	</screen>
	273	</para>
	274
	275	<para>
	276	The <literal>\q</literal> command above will quit the <command>psql</command>
	277	program and return you to the shell's command line prompt.
	278	</para>
	279
	280	<para>
	281	To improve security further, you could encrypt your database connections, or
	282	take any other step as needed. Please refer to <application>PostgreSQL</application>'s
	283	documentation for details.
	284	<warning>
	285	<title>Warning</title>
	286	<para>
	287	Defining passwords may not be sufficient if your database access rule is
	288	set to <literal>trust</literal> in the <filename>/etc/postgresql/pg_hba.conf</filename>.
	289	Again, please refer to <application>PostgreSQL</application>'s documentation
	290	for details. Also, passwords will fly unencrypted over the network by default,
	291	so be sure to take any necessary step to secure your database server from
	292	unauthorized use. This has nothing to do with <application>PyKota</application>
	293	though, it is just a general rule to keep in mind.
	294	</para>
	295	</warning>
	296	</para>
	297
	298	<para>
	299	For more details, please see <filename>initscripts/mysql/README.postgresql</filename>.
	300	</para>
	301
	302	<para>
	303	If no error occured, then your print quota database is ready to be used.
	304	Now you can let the print quota database server alone, the remaining work
	305	will have to be done on each one of the print servers which will
	306	use this particular print quota database server.
	307	<tip>
	308	<title>Tip</title>
	309	<para>
	310	If an error occured, maybe your PostgreSQL version is too old, or
	311	an unexpected problem (like a bug) happened. Please contact us via email so that we
	312	can try to fix the problem. Thanks in advance.
	313	</para>
	314	</tip>
	315	</para>
	316
	317	</sect3>
	318
	319	<sect3>
	320	<title>LDAP</title>
	321
	322	<para>
	323	Any <acronym>LDAP</acronym> server, and particularly <application>OpenLDAP</application>, can be used
	324	as a print quota database backend.
	325	Some other LDAP servers can be used, but this is currently untested in production.
	326	</para>
	327
	328	<para>
	329	<application>OpenLDAP</application> is a Lightweight Directory Access Protocol server
	330	implementation published as Free Software.
	331	You can download it from <ulink url="http://www.openldap.org">http://www.openldap.org</ulink>.
	332	</para>
	333
	334	<para>
	335	To use <application>OpenLDAP</application> as your print quota database backend, you have to copy the
	336	<filename>pykota/initscripts/ldap/pykota.schema</filename> into <application>OpenLDAP</application>'s
	337	schemas directory.
	338	Under Debian GNU/Linux, this is something like :
	339	<screen>
	340	$ cp pykota.schema /etc/ldap/schema
	341	</screen>
	342	<note>
	343	<title>Note</title>
	344	<para>
	345	If you use RPM or DEB packages, the
	346	<filename>pykota.schema</filename> file is usually installed into the
	347	<filename>/usr/share/pykota/ldap</filename> directory, along
	348	with a README file, and may also be installed automatically in
	349	your <acronym>LDAP</acronym> server's schemas directory.
	350	</para>
	351	</note>
	352	</para>
	353	<para>
	354	Then edit <filename>/etc/ldap/slapd.conf</filename> and add a line to
	355	include the PyKota schema. You should have something
	356	like :
	357	<screen>
	358	# Schema and objectClass definitions
	359	include /etc/ldap/schema/core.schema
	360	include /etc/ldap/schema/cosine.schema
	361	include /etc/ldap/schema/nis.schema
	362	include /etc/ldap/schema/inetorgperson.schema
	363	include /etc/ldap/schema/pykota.schema
	364	</screen>
	365	</para>
	366
	367	<para>
	368	While this is not mandatory, it is recommended that you setup
	369	some indexes for some often accessed PyKota attributes.
	370	Here are the minimal indexes
	371	lines you may want to put in <filename>slapd.conf</filename> :
	372	<screen>
	373	# Indexes for PyKota
	374	index pykotaUserName pres,eq,sub
	375	index pykotaGroupName pres,eq,sub
	376	index pykotaPrinterName pres,eq,sub
	377	index pykotaBillingCode pres,eq,sub
	378	index pykotaLastJobIdent eq
	379	</screen>
	380	</para>
	381
	382	<para>
	383	Now you must ensure that the DNs you'll use to bind to
	384	your OpenLDAP server don't have search queries size limits,
	385	which gives for example (OpenLDAP 2.1.x or above) :
	386
	387	<screen>
	388	# No Limits for PyKota's administrator and read-only user
	389	limits dn="cn=pykotaadmin,dc=example,dc=com" size.soft=-1 size.hard=soft
	390	limits dn="cn=pykotauser,dc=example,dc=com" size.soft=-1 size.hard=soft
	391	</screen>
	392
	393	Where pykotaadmin and pykotauser are the usernames used to bind to your
	394	OpenLDAP server within PyKota, respectively in ReadWrite mode
	395	(as set in pykotadmin.conf) and in ReadOnly mode (as set in pykota.conf).
	396	</para>
	397
	398	<para>
	399	Finally, stop the <application>OpenLDAP</application> server, generate
	400	the index files, and restart <application>OpenLDAP</application>
	401	<screen>
	402	$ /etc/init.d/slapd stop
	403	$ slapindex
	404	$ /etc/init.d/slapd start
	405	</screen>
	406	</para>
	407
	408	<para>
	409	With an <acronym>LDAP</acronym> backend, PyKota will need some branches
	410	in your <acronym>LDAP</acronym> directory to put its own datas.
	411	You can configure PyKota to either attach its datas to your existing
	412	users and groups, or to put them in their own <literal>ou</literal>.
	413	But some <literal>ou</literal>s dedicated to PyKota are needed in any case,
	414	so the best bet may be to put all PyKota's datas below an <literal>ou=PyKota</literal>
	415	branch. While this will separate these datas from your existing users and groups
	416	entries, this may ease the maintainance.
	417	</para>
	418
	419	<para>
	420	PyKota needs at least an <literal>ou</literal> for printers, for users quotas, for
	421	groups quotas, for print jobs, for billing codes, and for pointers to the last job of each printer.
	422	In the future, this last <literal>ou</literal> may disappear as its content
	423	will probably be attached to each printer.
	424	</para>
	425
	426	<para>
	427	Actually PyKota doesn't create these <literal>ou</literal>s for you, because it's
	428	difficult to guess what is the best configuration for you. So you have to
	429	create them by yourself, either directly with a text editor and the
	430	<command>ldapadd</command> command, or with some specialized tool
	431	like <command>gq</command>. You can look at the <filename>initscripts/ldap/pykota-sample.ldif</filename>
	432	file to see which minimal branches are necessary.
	433	<note>
	434	<title>Note</title>
	435	<para>
	436	If you use RPM or DEB packages, usually the
	437	<filename>pykota-sample.ldif</filename> file is installed into the
	438	<filename>/usr/share/pykota/ldap</filename> directory, along
	439	with a README file.
	440	</para>
	441	</note>
	442	</para>
	443
	444	<para>
	445	If no error occured, then your print quota database is ready to be used.
	446	Now you can let the print quota database server alone, the remaining work
	447	will have to be done on each one of the print servers which will
	448	use this particular print quota database server.
	449	<tip>
	450	<title>Tip</title>
	451	<para>
	452	If an error occured, maybe your OpenLDAP version is too old, or
	453	an unexpected problem (like a bug) happened. Please contact us via email so that we
	454	can try to fix the problem. Thanks in advance.
	455	</para>
	456	</tip>
	457	</para>
	458	</sect3>
	459
	460	<sect3>
	461	<title>MySQL</title>
	462
	463	<para>
	464	<application>MySQL</application> is a simple Relationnal DataBase
	465	Management System distributed under a <firstterm>Free Software</firstterm>
	466	license from the
	467	<ulink url="http://www.mysql.org">http://www.mysql.org</ulink>
	468	web site.
	469	</para>
	470
	471	<para>
	472	To configure your database, you must have MySQL version 4.1 or higher already working.
	473	We recommend that you use MySQL 5.0 or higher though.
	474	The complete installation of <application>MySQL</application> is not covered by
	475	the present manual, please refer to your system's documentation or to
	476	<ulink url="http://www.mysql.org">http://www.mysql.org</ulink> for
	477	details.
	478	</para>
	479
	480	<para>
	481	One thing you have to check, though, is that every Print Server on which you
	482	want to install the print quota mechanism, must be able to connect to the
	483	<application>MySQL</application> server. In the default installation of
	484	<application>MySQL</application> this may not be the case for security reasons, except if both
	485	servers are in fact the same machine. In any case, it is recommended that you
	486	check the <filename>/etc/mysql/my.cnf</filename> file and modify it if
	487	needed.
	488	<tip>
	489	<title>Tip</title>
	490	<para>
	491	Don't forget to restart <application>MySQL</application> if you modify
	492	any of its configuration files, in order for the changes to take effect.
	493	</para>
	494	</tip>
	495	</para>
	496
	497	<para>
	498	Be careful, you may be unable to connect from a Print Server to the <application>MySQL</application>
	499	server even if the configuration is correct. Sometimes your connections may be blocked by
	500	one or more network firewalls along the route from one machine to the other. If this
	501	is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm>
	502	to not filter the IP port used by <application>MySQL</application>, which is
	503	usually port <literal>3306/tcp</literal>.
	504	<note>
	505	<title>Note</title>
	506	<para>
	507	The TCP/IP network port used by MySQL may be different. When in doubt, ask your
	508	<firstterm>System Administrator</firstterm> for the correct value.
	509	</para>
	510	</note>
	511	</para>
	512
	513	<para>
	514	Now that your <application>MySQL</application> server is up and running, and
	515	is waiting for your connections, you have to create the print quota database.
	516	To do so, you'll have to feed <application>MySQL</application> with the
	517	<filename>pykota-1.25_official/initscripts/mysql/pykota-mysql.sql</filename> file.
	518	This file will create an empty
	519	print quota database and set some permissions on it.
	520	The database which will be created will be named <literal>pykota</literal> by default.
	521	Two database users will be defined to have access in readonly and read+write modes under
	522	the respective names <literal>pykotauser</literal> and <literal>pykotaadmin</literal>.
	523	The <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users by
	524	default respectively have <literal>readwritepw</literal> and <literal>readonlypw</literal>
	525	as their passwords.
	526	<note>
	527	<title>Note</title>
	528	<para>
	529	You can choose other names and passwords if you want by modifying the
	530	<filename>initscripts/mysql/pykota-mysql.sql</filename> file
	531	accordingly, and report your changes into <application>PyKota</application>'s
	532	configuration files.
	533	</para>
	534	</note>
	535	</para>
	536
	537	<para>
	538	To run this script, you can use the <command>mysql</command> frontend to
	539	<application>MySQL</application>, but your priviledges must be sufficient
	540	to be allowed to create databases. You can launch <command>mysql</command>
	541	as the <literal>root</literal> user for example.
	542	From a command line interpreter (i.e. shell), type the following commands :
	543	<screen>
	544	jerome@nordine:~$ cd pykota-1.25_official/initscripts/mysql
	545	jerome@nordine:~/pykota-1.25_official/initscripts$ mysql <pykota-mysql.sql
	546	</screen>
	547	<note>
	548	<title>Note</title>
	549	<para>
	550	If you use RPM or DEB packages, usually the
	551	<filename>pykota-mysql.sql</filename> file gets installed into the
	552	<filename>/usr/share/pykota/mysql</filename> directory, along
	553	with a README file.
	554	</para>
	555	</note>
	556	</para>
	557
	558	<para>
	559	To improve security further, you could encrypt your database connections, or
	560	take any other step as needed. Please refer to <application>MySQL</application>'s
	561	documentation for details.
	562	</para>
	563
	564	<para>
	565	For more details, please see <filename>initscripts/mysql/README.mysql</filename>.
	566	</para>
	567
	568	<para>
	569	If no error occured, then your print quota database is ready to be used.
	570	Now you can let the print quota database server alone, the remaining work
	571	will have to be done on each one of the print servers which will
	572	use this particular print quota database server.
	573	<tip>
	574	<title>Tip</title>
	575	<para>
	576	If an error occured, maybe your MySQL version is too old, or
	577	an unexpected problem (like a bug) happened. Please contact us via email so that we
	578	can try to fix the problem. Thanks in advance.
	579	</para>
	580	</tip>
	581	</para>
	582
	583	</sect3>
	584
	585	<sect3>
	586	<title>SQLite</title>
	587
	588	<para>
	589	<application>SQLite</application> is an embeddable Relationnal DataBase
	590	distributed under a Free Software
	591	license from the
	592	<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink>
	593	web site.
	594	If is very easy to configure and use, offers a very small memory footprint,
	595	is very fast, but can only be used on the print server because it doesn't include
	596	a server daemon : the database is directly embedded in the application.
	597	</para>
	598
	599	<para>
	600	To configure your database, you must have SQLite already working.
	601	The complete installation of <application>SQLite</application> is not covered by
	602	the present manual, please refer to your system's documentation or to
	603	<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink> for
	604	details.
	605	</para>
	606
	607	<para>
	608	Once <application>SQLite</application> is installed, you have to decide where
	609	you'll put your database. A good idea is to store it into the <literal>pykota</literal>
	610	user's home directory. Then to create the database, just type :
	611	<screen>
	612	# sqlite3 ~pykota/pykota.db <pykota/initscripts/sqlite/pykota.sqlite
	613	# chown pykota.pykota ~pykota/pykota.db
	614	# chmod 660 ~pykota/pykota.db
	615	# chown pykota.pykota ~pykota
	616	</screen>
	617	</para>
	618	<para>
	619	If user <literal>pykota</literal> doesn't exist yet, then please
	620	follow the instructions a bit below which explain how to install PyKota on the print server.
	621	</para>
	622
	623	<para>
	624	Once this is done, you'll want to set in <filename>~pykota/pykota.conf</filename> the
	625	following lines in the <literal>[global]</literal> section :
	626	<screen>
	627	storagebackend : sqlitestorage
	628	storagename : /etc/pykota/pykota.db
	629	</screen>
	630	</para>
	631	<para>
	632	Of course you'll want to replace the path on the <literal>storagename</literal> line
	633	with the full path to the newly created <application>SQLite</application> database.
	634	</para>
	635	<para>
	636	If no error occured, then your print quota database is ready to be used.
	637	In case you need them, additional instructions are available in <filename>pykota/initscripts/sqlite/README.sqlite</filename>
	638	<tip>
	639	<title>Tip</title>
	640	<para>
	641	If an error occured, maybe your SQLite version is too old, or
	642	an unexpected problem (like a bug) happened. Please contact us via email so that we
	643	can try to fix the problem. Thanks in advance.
	644	</para>
	645	</tip>
	646	</para>
	647	</sect3>
	648
	649	<sect3>
	650	<title>Berkeley DB</title>
	651
	652	<para>
	653	A <application>Berkeley DB</application> backend is planned, but it actually
	654	doesn't exist. It seems that remote storage won't be possible with such a backend,
	655	so in other terms this means that you will have a different quota database on
	656	each print server. This may still prove to be useful for small configurations.
	657	</para>
	658	</sect3>
	659	</sect2>
	660
	661	<sect2>
	662	<title>Print Server Installation</title>
	663
	664	<para>
	665	For each Print Server on which you plan to implement the print quota
	666	mechanism, you have, of course, to have an already working printing environment.
	667	Currently <application>PyKota</application> works with
	668	<ulink url="http://www.cups.org"><application>CUPS</application></ulink>
	669	but older releases also supported <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>.
	670	<application>LPRng</application> support might be re-added in the future.
	671	</para>
	672
	673	<para>
	674	Here's the list of software you have to install on each Print Server, version numbers
	675	are given as an indication of which was successfully tested, but older versions may
	676	work too.
	677	<itemizedlist>
	678	<listitem>
	679	<para>
	680	<application>CUPS</application> version 1.1.14 or higher, version 1.2.4 or higher
	681	is recommanded.
	682	You can download it from <ulink url="http://www.cups.org">http://www.cups.org</ulink>
	683	</para>
	684	</listitem>
	685	<listitem>
	686	<para>
	687	<application>Python</application> version 2.3 or higher.
	688	You can download it from <ulink url="http://www.python.org">http://www.python.org</ulink>.
	689	While <application>PyKota</application> itself will try to preserve compatibility
	690	with <application>Python</application> version 2.3 for the near future, some <application>Python</application>
	691	modules which are needed by <application>PyKota</application> may require a more recent version
	692	of this language.
	693	</para>
	694	</listitem>
	695	<listitem>
	696	<para>
	697	print quota database client libraries, depending on your print quota database backend :
	698	<itemizedlist>
	699	<listitem>
	700	<para>
	701	PostgreSQL backend :
	702	<itemizedlist>
	703	<listitem>
	704	<para>
	705	<application>PostgreSQL</application> client libraries. They must match the <application>PostgreSQL</application>
	706	version used on your print quota database server.
	707	</para>
	708	</listitem>
	709	<listitem>
	710	<para>
	711	The <application>PygreSQL</application> python module.
	712	<application>PygreSQL</application> is normally included in
	713	<application>PostgreSQL</application>, but you may want to
	714	download it from <ulink url="http://www.pygresql.org">http://www.pygresql.org</ulink>
	715	</para>
	716	</listitem>
	717	</itemizedlist>
	718	</para>
	719	</listitem>
	720	<listitem>
	721	<para>
	722	OpenLDAP backend :
	723	<itemizedlist>
	724	<listitem>
	725	<para>
	726	<application>OpenLDAP</application> client libraries. They must match
	727	the <application>OpenLDAP</application> version used on your print quota database server.
	728	</para>
	729	</listitem>
	730	<listitem>
	731	<para>
	732	The <application>Python-LDAP</application> python module.
	733	You may download this module from <ulink url="http://python-ldap.sourceforge.net">http://python-ldap.sourceforge.net</ulink>
	734	</para>
	735	</listitem>
	736	</itemizedlist>
	737	</para>
	738	</listitem>
	739	<listitem>
	740	<para>
	741	MySQL backend :
	742	<itemizedlist>
	743	<listitem>
	744	<para>
	745	<application>MySQL</application> client libraries. They must match the <application>MySQL</application>
	746	version used on your database server.
	747	</para>
	748	</listitem>
	749	<listitem>
	750	<para>
	751	The <application>Python-MySQL</application> python module, version 1.2.x or higher.
	752	You can download it from <ulink url="http://sourceforge.net/projects/mysql-python">http://sourceforge.net/projects/mysql-python</ulink>
	753	</para>
	754	</listitem>
	755	</itemizedlist>
	756	</para>
	757	</listitem>
	758	<listitem>
	759	<para>
	760	SQLite backend : SQLite is not a database server, but an embeddable database, so
	761	if you want to use it you MUST install SQLite on your print server. With
	762	<application>PostgreSQL</application>, <application>MySQL</application> or
	763	<application>OpenLDAP</application> you can store your datas on a different
	764	machine than the print server, but this is not possible with <application>SQLite</application>.
	765	<itemizedlist>
	766	<listitem>
	767	<para>
	768	<application>SQLite</application> version 3.2.1 or higher and its library.
	769	You can download it from
	770	<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink>
	771	</para>
	772	</listitem>
	773	<listitem>
	774	<para>
	775	The <application>Python-SQLite</application> python module version 2.0.5 or higher.
	776	You can download it from
	777	<ulink url="http://www.pysqlite.org">http://www.pysqlite.org</ulink>
	778	</para>
	779	</listitem>
	780	</itemizedlist>
	781	</para>
	782	</listitem>
	783	<listitem>
	784	<para>
	785	Berkeley DB backend : Not supported yet.
	786	</para>
	787	</listitem>
	788	</itemizedlist>
	789	</para>
	790	</listitem>
	791	<listitem>
	792	<para>
	793	<application>ucd-snmp</application> or <application>net-snmp</application> tools, version 4.2.5 or above. You only need
	794	the <command>snmpget</command> command.
	795	You can download this software from <ulink url="http://www.sourceforge.net/projects/net-snmp/">http://www.sourceforge.net/projects/net-snmp/</ulink>.
	796	You only need this if PyKota's internal SNMP accounting code doesn't work for your SNMP-aware
	797	printers.
	798	</para>
	799	</listitem>
	800	<listitem>
	801	<para>
	802	<application>netatalk</application> version 1.6.1 or above. You only need
	803	the <command>pap</command> command.
	804	You can download this software from <ulink url="http://netatalk.sourceforge.net/">http://netatalk.sourceforge.net/</ulink>.
	805	You only need this if you plan to query your printers for their internal page counter via AppleTalk.
	806	</para>
	807	</listitem>
	808	<listitem>
	809	<para>
	810	eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version.
	811	You can download it from <ulink url="http://www.egenix.com">http://www.egenix.com</ulink>.
	812	</para>
	813	</listitem>
	814	<listitem>
	815	<para>
	816	The Python acccelerator <application>Psyco</application>. It must match your default Python version.
	817	You can download it from <ulink url="http://psyco.sourceforge.net">http://psyco.sourceforge.net</ulink>.
	818	You only need this if you run on the <literal>x86</literal> architecture because
	819	<application>Psyco</application> doesn't yet exist on other architectures.
	820	</para>
	821	</listitem>
	822	<listitem>
	823	<para>
	824	The <application>pysnmp</application> Python module version 3.4.2, or higher, version 4 is recommanded.
	825	You can download it from <ulink url="http://pysnmp.sourceforge.net">http://pysnmp.sourceforge.net</ulink>.
	826	</para>
	827	</listitem>
	828	<listitem>
	829	<para>
	830	The <application>JAXML</application> Python module.
	831	You can download it from <ulink url="http://www.librelogiciel.com/software/">http://www.librelogiciel.com/software/</ulink>.
	832	</para>
	833	</listitem>
	834	<listitem>
	835	<para>
	836	The <application>ReportLab</application> Toolkit Python module.
	837	You can download it from <ulink url="http://www.reportlab.org">http://www.reportlab.org</ulink>.
	838	</para>
	839	</listitem>
	840	<listitem>
	841	<para>
	842	The <application>Python Imaging Library - PIL</application> module.
	843	You can download it from <ulink url="http://www.pythonware.com">http://www.pythonware.com</ulink>.
	844	</para>
	845	</listitem>
	846	<listitem>
	847	<para>
	848	The <application>PyOSD</application> Python module.
	849	You can download it from <ulink url="http://repose.cx/pyosd/">http://repose.cx/pyosd/</ulink>.
	850	</para>
	851	</listitem>
	852	<listitem>
	853	<para>
	854	The <application>pkpgcounter</application> Generic Page Description Language parser.
	855	You can download it from <ulink url="http://www.pykota.com.com/software/pkpgcounter">http://www.pykota.com/software/pkpgcounter</ulink>.
	856	</para>
	857	</listitem>
	858	<listitem>
	859	<para>
	860	The <application>PyPAM</application> Python interface to <acronym>PAM</acronym>.
	861	You'll need this if you plan to ask users to authenticate when printing through <command>pknotify</command>
	862	and <command>pykoticon</command>. You don't need this module otherwise.
	863	If needed, you can download it from <ulink url="http://www.pangalactic.org/PyPAM/">http://www.pangalactic.org/PyPAM/</ulink>.
	864	</para>
	865	</listitem>
	866	<listitem>
	867	<para>
	868	The <application>PkIPPLib</application> Python <acronym>IPP</acronym> library.
	869	You can download it from <ulink url="http://www.pykota.com/software/pkipplib">http://www.pykota.com/software/pkipplib</ulink>.
	870	</para>
	871	</listitem>
	872	</itemizedlist>
	873	</para>
	874
	875	<para>
	876	Instead of downloading all these programs' sources and compiling them, which really
	877	is a boring task considering that many software are needed, you may prefer to look
	878	into the packages included with your GNU/Linux distribution of choice (if you use
	879	this operating system of course). Most, if not all, GNU/Linux distributions include
	880	all the software mentionned above, in the form of packages which are easier to
	881	install than sources tarballs. This is probably the same for the many *BSD
	882	distributions.
	883	</para>
	884
	885	<para>
	886	You can check that all needed software is installed by launching the <command>checkdeps.py</command>
	887	command :
	888	<screen>
	889	$ python checkdeps.py
	890	</screen>
	891	</para>
	892
	893	<para>
	894	Once all these software are installed, installing PyKota itself is a breeze.
	895	PyKota being written entirely in the Python language, which is interpreted,
	896	there's no need to compile anything. You just have to execute the installation
	897	script :
	898	<screen>
	899	$ python setup.py install
	900	</screen>
	901	</para>
	902
	903	<para>
	904	The setup script will automatically create the
	905	<filename>/usr/share/pykota/conf</filename> directory and put the sample
	906	configuration files <filename>conf/pykota.conf.sample</filename> and
	907	<filename>conf/pykotadmin.conf.sample</filename> there, along with
	908	a <filename>README</filename> file explaining their purpose.
	909	</para>
	910
	911	<para>
	912	Now you have to create a <literal>pykota</literal> system user and group. The <application>PyKota</application>
	913	software will automatically search its configuration files in user <literal>pykota</literal>'s
	914	home directory. For example we could create the user and group, and set <filename>/etc/pykota</filename>
	915	as the home directory, but any other home directory will do :
	916	<screen>
	917	adduser --system --group --home /etc/pykota --gecos PyKota pykota
	918	</screen>
	919	</para>
	920
	921	<para>
	922	You now have to copy the sample configuration files into the <filename>~pykota</filename>
	923	directory, under the respective names <filename>pykota.conf</filename> and
	924	<filename>pykotadmin.conf</filename>. Once copied there, you just
	925	have to modify these files to adapt them to your own setup.
	926	These files are heavily commented, so you should have no problem.
	927	Also their format is quite common, because it's the one used by
	928	<application>Samba</application> for example, or by <literal>.ini</literal>
	929	files under <application>MS-Windows</application>, so you may already
	930	be familiar with this syntax.
	931	In a future release, this documentation will include the complete
	932	reference for all configuration fields available. Keep in mind that
	933	<application>PyKota</application> can be really heavily customized, and can delegate some work
	934	to any external command of your choice.
	935	</para>
	936
	937	<para>
	938	Please create a backup copy of the <filename>~pykota</filename>
	939	directory before modifying a working installation.
	940	</para>
	941
	942	<para>
	943	PyKota features some interesting possibilities which allow you to
	944	define options either globally so that they apply to all printers,
	945	or on a per printer basis. Please see the sample configuration files
	946	to see what I mean. In the simplest form, only a <literal>[global]</literal> section is
	947	needed. In more complex configurations, you will have to create
	948	one section per printer. Each section in the configuration files
	949	begins with a name between square brackets <literal>[]</literal>.
	950	The name to use to define a particular printer section is the name
	951	of the print queue you want to manage with PyKota.
	952	</para>
	953
	954	<para>
	955	After you have modified <application>PyKota</application>'s configuration files, you have to
	956	double check their permissions, otherwise your installation may be
	957	insecure or may not work at all.
	958	The main configuration file <filename>~pykota/pykota.conf</filename>
	959	doesn't contain much sensitive information, so it can be made
	960	readable by anyone. If normal users read this file, at best they
	961	will learn the username and optional password of the read-only
	962	database user. This means that beside being allowed to read all the contents of
	963	the quota database, they won't be allowed to modify or delete it.
	964	On the other hand, the <filename>~pykota/pykotadmin.conf</filename>
	965	file contains the read-write user's identity and password. You must then
	966	ensure that no normal user can read this file. It should only be readable
	967	by the <literal>root</literal> user, which is always the case, and by
	968	<application>PyKota</application> administrators. In addition,
	969	users for which <application>CUPS</application> doesn't run as user <literal>root</literal> will
	970	have to ensure that the user their printing system is run as
	971	can read both of these files. An easy way to do so is to put the <literal>lp</literal> user
	972	(for example) into the <literal>pykota</literal> system group, then
	973	to give the correct permissions to <application>PyKota</application>'s configuration files :
198	974	<screen>
199		jerome@nordine:~$ cd pykota-1.25_official/initscripts/postgresql
200		jerome@nordine:~/pykota-1.25_official/initscripts$ psql -h localhost -U postgres template1
201		Welcome to psql, the PostgreSQL interactive terminal.
202
203		Type: \copyright for distribution terms
204		\h for help with SQL commands
205		\? for help on internal slash commands
206		\g or terminate with semicolon to execute query
207		\q to quit
208
209		template1=# \i pykota-postgresql.sql
210		... a lot of output lines
211		pykota=#
	975	$ chown -R pykota.pykota ~pykota/
	976	$ chmod 750 ~pykota/
	977	$ chmod 644 ~pykota/pykota.conf
	978	$ chmod 640 ~pykota/pykotadmin.conf
212	979	</screen>
213		<note>
214		<title>Note</title>
215		<para>
216		If you use RPM or DEB packages, usually the
217		<filename>pykota-postgresql.sql</filename> file gets installed into the
218		<filename>/usr/share/pykota/postgresql</filename> directory, along
219		with a README file.
220		</para>
221		</note>
222		</para>
223
224		<para>
225		If you want to you can change passwords later in
226		<application>PostgreSQL</application> for the
227		<literal>pykotaadmin</literal> and <literal>pykotauser</literal> users.
228		To do so, just type the following lines while still being at the <command>psql</command>
229		prompt (replace the password values by your own :
230		<screen>
231		pykota=# ALTER USER pykotaadmin PASSWORD 'somepassword';
232		ALTER USER
233		pykota=# ALTER USER pykotauser PASSWORD 'anotherpassword';
234		pykota=# \q
235		jerome@nordine:~/pykota-1.25_official/initscripts/postgresql$
236		</screen>
237		</para>
238
239		<para>
240		The <literal>\q</literal> command above will quit the <command>psql</command>
241		program and return you to the shell's command line prompt.
242		</para>
243
244		<para>
245		To improve security further, you could encrypt your database connections, or
246		take any other step as needed. Please refer to <application>PostgreSQL</application>'s
247		documentation for details.
	980
248	981	<warning>
249	982	<title>Warning</title>
250	983	<para>
251		Defining passwords may not be sufficient if your database access rule is
252		set to <literal>trust</literal> in the <filename>/etc/postgresql/pg_hba.conf</filename>.
253		Again, please refer to <application>PostgreSQL</application>'s documentation
254		for details. Also, passwords will fly unencrypted over the network by default,
255		so be sure to take any necessary step to secure your database server from
256		unauthorized use. This has nothing to do with <application>PyKota</application>
257		though, it is just a general rule to keep in mind.
	984	All the users allowed to read the <filename>~pykota/pykotadmin.conf</filename>
	985	are considered to be <application>PyKota</application> administrators. So be
	986	careful with these files permissions.
258	987	</para>
259		</warning>
260		</para>
261
262		<para>
263		For more details, please see <filename>initscripts/mysql/README.postgresql</filename>.
264		</para>
265
266		<para>
267		If no error occured, then your print quota database is ready to be used.
268		Now you can let the print quota database server alone, the remaining work
269		will have to be done on each one of the print servers which will
270		use this particular print quota database server.
271		<tip>
272		<title>Tip</title>
	988	</warning>
	989	</para>
	990
	991	<para>
	992	On some systems, you may be able to strenghten permissions like this :
	993	<screen>
	994	$ chown -R pykota.pykota ~pykota/
	995	$ chmod 750 ~pykota/
	996	$ chmod 640 ~pykota/pykota.conf
	997	$ chmod 600 ~pykota/pykotadmin.conf
	998	</screen>
	999	</para>
	1000
	1001	<para>
	1002	And on other ones, you may need to relax them, and change the files' owner :
	1003	<screen>
	1004	$ chown pykota.pykota ~pykota/
	1005	$ chmod 755 ~pykota/
	1006	$ chown lp.pykota ~pykota/pykota.conf
	1007	$ chmod 640 ~pykota/pykota.conf
	1008	$ chown lp.pykota ~pykota/pykotadmin.conf
	1009	$ chmod 640 ~pykota/pykotadmin.conf
	1010	</screen>
	1011	</para>
	1012
	1013	<para>
	1014	This all depends on the printing system you are using, and the user the
	1015	printing system is usually running as. You need to remember three things :
	1016
	1017	<itemizedlist>
	1018	<listitem>
	1019	<para>
	1020	The user your printing system runs as MUST be allowed to read
	1021	both <application>PyKota</application>'s configuration files.
	1022	</para>
	1023	</listitem>
	1024	<listitem>
	1025	<para>
	1026	Any user who can read <filename>pykotadmin.conf</filename>
	1027	is a <application>PyKota</application> administrator, and
	1028	can do whatever he wants to the print quota database.
	1029	</para>
	1030	</listitem>
	1031	<listitem>
	1032	<para>
	1033	If <filename>cupsd.conf</filename> contains <literal>RunAsUser</literal>, then
	1034	you won't be able to authenticate users with <command>pknotify</command> and <command>pykoticon</command>.
	1035	Also in this case you may have to make <application>PyKota</application>'s configuration files
	1036	owned by the user <application>CUPS</application> runs as.
	1037	</para>
	1038	</listitem>
	1039	</itemizedlist>
	1040	</para>
	1041
	1042	<para>
	1043	Don't forget to restart your print server sofware if you changed group membership for the user it runs
	1044	as, otherwise your change wouldn't be taken into account.
	1045	</para>
	1046
	1047	<para>
	1048	Now depending on your printing system, the configuration to do is particular.
	1049	We will now see how to plug PyKota into <application>CUPS</application> since <application>LPRng</application>
	1050	is not supported anymore.
	1051	</para>
	1052
	1053	<sect3>
	1054	<title>With CUPS</title>
	1055
	1056	<para>
	1057	From version 1.16alpha7 on, configuring <application>PyKota</application> to integrate
	1058	within <application>CUPS</application> is more than easy.
	1059	</para>
	1060
	1061	<para>
	1062	You just have to create a symbolic link to the <command>cupspykota</command>
	1063	command in <application>CUPS</application>' backend directory :
	1064	<screen>
	1065	$ cd /usr/lib/cups/backend
	1066	$ ln -s /usr/share/pykota/cupspykota cupspykota
	1067	</screen>
	1068	</para>
	1069
	1070	<para>
	1071	If you use CUPS v1.2 or higher, you must
	1072	also type the following command to allow the <command>cupspykota</command>
	1073	backend to correctly support other backends which must be run
	1074	as the root user (e.g. the <command>lpd</command> backend) :
	1075	<screen>
	1076	$ chmod 700 /usr/share/pykota/cupspykota
	1077	</screen>
	1078	</para>
	1079
	1080	<para>
	1081	You have to restart <application>CUPS</application> for this modification to
	1082	take effect :
	1083	<screen>
	1084	$ /etc/init.d/cupsys restart
	1085	</screen>
	1086	</para>
	1087
	1088	<para>
	1089	Now point your web browser to CUPS configuration page, usually at
	1090	<ulink url="http://localhost:631">http://localhost:631</ulink> on
	1091	your print server.
	1092	</para>
	1093
	1094	<para>
	1095	Then when creating new printers or reconfiguring existing ones, just
	1096	choose devices which are <literal>PyKota managed</literal>
	1097	<footnote>
	1098	<para>
	1099	Debian 3.0 Woody is known to have problems : CUPS 1.1.14 doesn't automatically
	1100	detect <literal>PyKota managed</literal> devices. So you have to manually
	1101	modify CUPS' <filename>printers.conf</filename> file as explained in
	1102	PyKota's toplevel <filename>README</filename> file.
	1103	</para>
	1104	</footnote>
	1105	instead of
	1106	normal devices. You've got one <literal>PyKota managed</literal> device
	1107	for each regular device available from CUPS, so just choose the appropriate
	1108	one.
	1109	</para>
	1110
	1111	<para>
	1112	Repeat the above procedure for each print queue on which you want to use
	1113	PyKota. That's all !
	1114	</para>
	1115
	1116	<sect4>
	1117	<title>Troubleshooting</title>
273	1118	<para>
274		I~~f an error occured, maybe your PostgreSQL version is too old, or~~
275		~~an unexpected problem (like a bug) happened. Please contact us via email so that we~~
276		~~can try to fix the problem. Thanks in advanc~~e.
	1119	In case of problem, the simplest way to solve it is currently
	1120	to ask on PyKota's mailing list, describing the symptoms, as
	1121	well as the hardware and software you use.
277	1122	</para>
278		</tip>
279		</para>
	1123
	1124	<para>
	1125	A searchable FAQ is now available at
	1126	<ulink url="http://otrs.librelogiciel.com/otrs/public.pl">http://otrs.librelogiciel.com/public.pl</ulink>.
	1127	A FAQ entry explaining in great details how to diagnose a problem correctly is
	1128	available at
	1129	<ulink url="http://otrs.librelogiciel.com/otrs/public.pl?ID=2">http://otrs.librelogiciel.com/public.pl?ID=2</ulink>.
	1130	</para>
	1131
	1132	<para>
	1133	You can also ask questions on IRC :
	1134	<screen>
	1135	/server irc.freenode.net
	1136	/join #pykota
	1137	</screen>
	1138	</para>
	1139	</sect4>
	1140
	1141	</sect3>
280	1142
281	1143	</sect2>
282
283		<sect2>
284		<title>LDAP</title>
285
286		<para>
287		Any <acronym>LDAP</acronym> server, and particularly <application>OpenLDAP</application>, can be used
288		as a print quota database backend.
289		Some other LDAP servers can be used, but this is currently untested in production.
290		</para>
291
292		<para>
293		<application>OpenLDAP</application> is a Lightweight Directory Access Protocol server
294		implementation published as Free Software.
295		You can download it from <ulink url="http://www.openldap.org">http://www.openldap.org</ulink>.
296		</para>
297
298		<para>
299		To use <application>OpenLDAP</application> as your print quota database backend, you have to copy the
300		<filename>pykota/initscripts/ldap/pykota.schema</filename> into <application>OpenLDAP</application>'s
301		schemas directory.
302		Under Debian GNU/Linux, this is something like :
303		<screen>
304		$ cp pykota.schema /etc/ldap/schema
305		</screen>
306		<note>
307		<title>Note</title>
308		<para>
309		If you use RPM or DEB packages, the
310		<filename>pykota.schema</filename> file is usually installed into the
311		<filename>/usr/share/pykota/ldap</filename> directory, along
312		with a README file, and may also be installed automatically in
313		your <acronym>LDAP</acronym> server's schemas directory.
314		</para>
315		</note>
316		</para>
317		<para>
318		Then edit <filename>/etc/ldap/slapd.conf</filename> and add a line to
319		include the PyKota schema. You should have something
320		like :
321		<screen>
322		# Schema and objectClass definitions
323		include /etc/ldap/schema/core.schema
324		include /etc/ldap/schema/cosine.schema
325		include /etc/ldap/schema/nis.schema
326		include /etc/ldap/schema/inetorgperson.schema
327		include /etc/ldap/schema/pykota.schema
328		</screen>
329		</para>
330
331		<para>
332		While this is not mandatory, it is recommended that you setup
333		some indexes for some often accessed PyKota attributes.
334		Here are the minimal indexes
335		lines you may want to put in <filename>slapd.conf</filename> :
336		<screen>
337		# Indexes for PyKota
338		index pykotaUserName pres,eq,sub
339		index pykotaGroupName pres,eq,sub
340		index pykotaPrinterName pres,eq,sub
341		index pykotaBillingCode pres,eq,sub
342		index pykotaLastJobIdent eq
343		</screen>
344		</para>
345
346		<para>
347		Now you must ensure that the DNs you'll use to bind to
348		your OpenLDAP server don't have search queries size limits,
349		which gives for example (OpenLDAP 2.1.x or above) :
350
351		<screen>
352		# No Limits for PyKota's administrator and read-only user
353		limits dn="cn=pykotaadmin,dc=example,dc=com" size.soft=-1 size.hard=soft
354		limits dn="cn=pykotauser,dc=example,dc=com" size.soft=-1 size.hard=soft
355		</screen>
356
357		Where pykotaadmin and pykotauser are the usernames used to bind to your
358		OpenLDAP server within PyKota, respectively in ReadWrite mode
359		(as set in pykotadmin.conf) and in ReadOnly mode (as set in pykota.conf).
360		</para>
361
362		<para>
363		Finally, stop the <application>OpenLDAP</application> server, generate
364		the index files, and restart <application>OpenLDAP</application>
365		<screen>
366		$ /etc/init.d/slapd stop
367		$ slapindex
368		$ /etc/init.d/slapd start
369		</screen>
370		</para>
371
372		<para>
373		With an <acronym>LDAP</acronym> backend, PyKota will need some branches
374		in your <acronym>LDAP</acronym> directory to put its own datas.
375		You can configure PyKota to either attach its datas to your existing
376		users and groups, or to put them in their own <literal>ou</literal>.
377		But some <literal>ou</literal>s dedicated to PyKota are needed in any case,
378		so the best bet may be to put all PyKota's datas below an <literal>ou=PyKota</literal>
379		branch. While this will separate these datas from your existing users and groups
380		entries, this may ease the maintainance.
381		</para>
382
383		<para>
384		PyKota needs at least an <literal>ou</literal> for printers, for users quotas, for
385		groups quotas, for print jobs, for billing codes, and for pointers to the last job of each printer.
386		In the future, this last <literal>ou</literal> may disappear as its content
387		will probably be attached to each printer.
388		</para>
389
390		<para>
391		Actually PyKota doesn't create these <literal>ou</literal>s for you, because it's
392		difficult to guess what is the best configuration for you. So you have to
393		create them by yourself, either directly with a text editor and the
394		<command>ldapadd</command> command, or with some specialized tool
395		like <command>gq</command>. You can look at the <filename>initscripts/ldap/pykota-sample.ldif</filename>
396		file to see which minimal branches are necessary.
397		<note>
398		<title>Note</title>
399		<para>
400		If you use RPM or DEB packages, usually the
401		<filename>pykota-sample.ldif</filename> file is installed into the
402		<filename>/usr/share/pykota/ldap</filename> directory, along
403		with a README file.
404		</para>
405		</note>
406		</para>
407
408		<para>
409		If no error occured, then your print quota database is ready to be used.
410		Now you can let the print quota database server alone, the remaining work
411		will have to be done on each one of the print servers which will
412		use this particular print quota database server.
413		<tip>
414		<title>Tip</title>
415		<para>
416		If an error occured, maybe your OpenLDAP version is too old, or
417		an unexpected problem (like a bug) happened. Please contact us via email so that we
418		can try to fix the problem. Thanks in advance.
419		</para>
420		</tip>
421		</para>
422		</sect2>
423
424		<sect2>
425		<title>MySQL</title>
426
427		<para>
428		<application>MySQL</application> is a simple Relationnal DataBase
429		Management System distributed under a <firstterm>Free Software</firstterm>
430		license from the
431		<ulink url="http://www.mysql.org">http://www.mysql.org</ulink>
432		web site.
433		</para>
434
435		<para>
436		To configure your database, you must have MySQL version 4.1 or higher already working.
437		We recommend that you use MySQL 5.0 or higher though.
438		The complete installation of <application>MySQL</application> is not covered by
439		the present manual, please refer to your system's documentation or to
440		<ulink url="http://www.mysql.org">http://www.mysql.org</ulink> for
441		details.
442		</para>
443
444		<para>
445		One thing you have to check, though, is that every Print Server on which you
446		want to install the print quota mechanism, must be able to connect to the
447		<application>MySQL</application> server. In the default installation of
448		<application>MySQL</application> this may not be the case for security reasons, except if both
449		servers are in fact the same machine. In any case, it is recommended that you
450		check the <filename>/etc/mysql/my.cnf</filename> file and modify it if
451		needed.
452		<tip>
453		<title>Tip</title>
454		<para>
455		Don't forget to restart <application>MySQL</application> if you modify
456		any of its configuration files, in order for the changes to take effect.
457		</para>
458		</tip>
459		</para>
460
461		<para>
462		Be careful, you may be unable to connect from a Print Server to the <application>MySQL</application>
463		server even if the configuration is correct. Sometimes your connections may be blocked by
464		one or more network firewalls along the route from one machine to the other. If this
465		is the case, then the best thing you can do is to ask your <firstterm>Network Administrator</firstterm>
466		to not filter the IP port used by <application>MySQL</application>, which is
467		usually port <literal>3306/tcp</literal>.
468		<note>
469		<title>Note</title>
470		<para>
471		The TCP/IP network port used by MySQL may be different. When in doubt, ask your
472		<firstterm>System Administrator</firstterm> for the correct value.
473		</para>
474		</note>
475		</para>
476
477		<para>
478		Now that your <application>MySQL</application> server is up and running, and
479		is waiting for your connections, you have to create the print quota database.
480		To do so, you'll have to feed <application>MySQL</application> with the
481		<filename>pykota-1.25_official/initscripts/mysql/pykota-mysql.sql</filename> file.
482		This file will create an empty
483		print quota database and set some permissions on it.
484		The database which will be created will be named <literal>pykota</literal> by default.
485		Two database users will be defined to have access in readonly and read+write modes under
486		the respective names <literal>pykotauser</literal> and <literal>pykotaadmin</literal>.
487		The <literal>pykotaadmin</literal> and <literal>pykotauser</literal> users by
488		default respectively have <literal>readwritepw</literal> and <literal>readonlypw</literal>
489		as their passwords.
490		<note>
491		<title>Note</title>
492		<para>
493		You can choose other names and passwords if you want by modifying the
494		<filename>initscripts/mysql/pykota-mysql.sql</filename> file
495		accordingly, and report your changes into <application>PyKota</application>'s
496		configuration files.
497		</para>
498		</note>
499		</para>
500
501		<para>
502		To run this script, you can use the <command>mysql</command> frontend to
503		<application>MySQL</application>, but your priviledges must be sufficient
504		to be allowed to create databases. You can launch <command>mysql</command>
505		as the <literal>root</literal> user for example.
506		From a command line interpreter (i.e. shell), type the following commands :
507		<screen>
508		jerome@nordine:~$ cd pykota-1.25_official/initscripts/mysql
509		jerome@nordine:~/pykota-1.25_official/initscripts$ mysql <pykota-mysql.sql
510		</screen>
511		<note>
512		<title>Note</title>
513		<para>
514		If you use RPM or DEB packages, usually the
515		<filename>pykota-mysql.sql</filename> file gets installed into the
516		<filename>/usr/share/pykota/mysql</filename> directory, along
517		with a README file.
518		</para>
519		</note>
520		</para>
521
522		<para>
523		To improve security further, you could encrypt your database connections, or
524		take any other step as needed. Please refer to <application>MySQL</application>'s
525		documentation for details.
526		</para>
527
528		<para>
529		For more details, please see <filename>initscripts/mysql/README.mysql</filename>.
530		</para>
531
532		<para>
533		If no error occured, then your print quota database is ready to be used.
534		Now you can let the print quota database server alone, the remaining work
535		will have to be done on each one of the print servers which will
536		use this particular print quota database server.
537		<tip>
538		<title>Tip</title>
539		<para>
540		If an error occured, maybe your MySQL version is too old, or
541		an unexpected problem (like a bug) happened. Please contact us via email so that we
542		can try to fix the problem. Thanks in advance.
543		</para>
544		</tip>
545		</para>
546
547		</sect2>
548
549		<sect2>
550		<title>SQLite</title>
551
552		<para>
553		<application>SQLite</application> is an embeddable Relationnal DataBase
554		distributed under a Free Software
555		license from the
556		<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink>
557		web site.
558		If is very easy to configure and use, offers a very small memory footprint,
559		is very fast, but can only be used on the print server because it doesn't include
560		a server daemon : the database is directly embedded in the application.
561		</para>
562
563		<para>
564		To configure your database, you must have SQLite already working.
565		The complete installation of <application>SQLite</application> is not covered by
566		the present manual, please refer to your system's documentation or to
567		<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink> for
568		details.
569		</para>
570
571		<para>
572		Once <application>SQLite</application> is installed, you have to decide where
573		you'll put your database. A good idea is to store it into the <literal>pykota</literal>
574		user's home directory. Then to create the database, just type :
575		<screen>
576		# sqlite3 ~pykota/pykota.db <pykota/initscripts/sqlite/pykota.sqlite
577		# chown pykota.pykota ~pykota/pykota.db
578		# chmod 660 ~pykota/pykota.db
579		# chown pykota.pykota ~pykota
580		</screen>
581		</para>
582		<para>
583		If user <literal>pykota</literal> doesn't exist yet, then please
584		follow the instructions a bit below which explain how to install PyKota on the print server.
585		</para>
586
587		<para>
588		Once this is done, you'll want to set in <filename>~pykota/pykota.conf</filename> the
589		following lines in the <literal>[global]</literal> section :
590		<screen>
591		storagebackend : sqlitestorage
592		storagename : /etc/pykota/pykota.db
593		</screen>
594		</para>
595		<para>
596		Of course you'll want to replace the path on the <literal>storagename</literal> line
597		with the full path to the newly created <application>SQLite</application> database.
598		</para>
599		<para>
600		If no error occured, then your print quota database is ready to be used.
601		In case you need them, additional instructions are available in <filename>pykota/initscripts/sqlite/README.sqlite</filename>
602		<tip>
603		<title>Tip</title>
604		<para>
605		If an error occured, maybe your SQLite version is too old, or
606		an unexpected problem (like a bug) happened. Please contact us via email so that we
607		can try to fix the problem. Thanks in advance.
608		</para>
609		</tip>
610		</para>
611		</sect2>
612
613		<sect2>
614		<title>Berkeley DB</title>
615
616		<para>
617		A <application>Berkeley DB</application> backend is planned, but it actually
618		doesn't exist. It seems that remote storage won't be possible with such a backend,
619		so in other terms this means that you will have a different quota database on
620		each print server. This may still prove to be useful for small configurations.
621		</para>
622		</sect2>
623		</sect1>
624
625		<sect1>
626		<title>Print Server Installation</title>
627
628		<para>
629		For each Print Server on which you plan to implement the print quota
630		mechanism, you have, of course, to have an already working printing environment.
631		Currently <application>PyKota</application> works with
632		<ulink url="http://www.cups.org"><application>CUPS</application></ulink>
633		but older releases also supported <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>.
634		<application>LPRng</application> support might be re-added in the future.
635		</para>
636
637		<para>
638		Here's the list of software you have to install on each Print Server, version numbers
639		are given as an indication of which was successfully tested, but older versions may
640		work too.
641		<itemizedlist>
642		<listitem>
643		<para>
644		<application>CUPS</application> version 1.1.14 or higher, version 1.2.4 or higher
645		is recommanded.
646		You can download it from <ulink url="http://www.cups.org">http://www.cups.org</ulink>
647		</para>
648		</listitem>
649		<listitem>
650		<para>
651		<application>Python</application> version 2.3 or higher.
652		You can download it from <ulink url="http://www.python.org">http://www.python.org</ulink>.
653		While <application>PyKota</application> itself will try to preserve compatibility
654		with <application>Python</application> version 2.3 for the near future, some <application>Python</application>
655		modules which are needed by <application>PyKota</application> may require a more recent version
656		of this language.
657		</para>
658		</listitem>
659		<listitem>
660		<para>
661		print quota database client libraries, depending on your print quota database backend :
662		<itemizedlist>
663		<listitem>
664		<para>
665		PostgreSQL backend :
666		<itemizedlist>
667		<listitem>
668		<para>
669		<application>PostgreSQL</application> client libraries. They must match the <application>PostgreSQL</application>
670		version used on your print quota database server.
671		</para>
672		</listitem>
673		<listitem>
674		<para>
675		The <application>PygreSQL</application> python module.
676		<application>PygreSQL</application> is normally included in
677		<application>PostgreSQL</application>, but you may want to
678		download it from <ulink url="http://www.pygresql.org">http://www.pygresql.org</ulink>
679		</para>
680		</listitem>
681		</itemizedlist>
682		</para>
683		</listitem>
684		<listitem>
685		<para>
686		OpenLDAP backend :
687		<itemizedlist>
688		<listitem>
689		<para>
690		<application>OpenLDAP</application> client libraries. They must match
691		the <application>OpenLDAP</application> version used on your print quota database server.
692		</para>
693		</listitem>
694		<listitem>
695		<para>
696		The <application>Python-LDAP</application> python module.
697		You may download this module from <ulink url="http://python-ldap.sourceforge.net">http://python-ldap.sourceforge.net</ulink>
698		</para>
699		</listitem>
700		</itemizedlist>
701		</para>
702		</listitem>
703		<listitem>
704		<para>
705		MySQL backend :
706		<itemizedlist>
707		<listitem>
708		<para>
709		<application>MySQL</application> client libraries. They must match the <application>MySQL</application>
710		version used on your database server.
711		</para>
712		</listitem>
713		<listitem>
714		<para>
715		The <application>Python-MySQL</application> python module, version 1.2.x or higher.
716		You can download it from <ulink url="http://sourceforge.net/projects/mysql-python">http://sourceforge.net/projects/mysql-python</ulink>
717		</para>
718		</listitem>
719		</itemizedlist>
720		</para>
721		</listitem>
722		<listitem>
723		<para>
724		SQLite backend : SQLite is not a database server, but an embeddable database, so
725		if you want to use it you MUST install SQLite on your print server. With
726		<application>PostgreSQL</application>, <application>MySQL</application> or
727		<application>OpenLDAP</application> you can store your datas on a different
728		machine than the print server, but this is not possible with <application>SQLite</application>.
729		<itemizedlist>
730		<listitem>
731		<para>
732		<application>SQLite</application> version 3.2.1 or higher and its library.
733		You can download it from
734		<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink>
735		</para>
736		</listitem>
737		<listitem>
738		<para>
739		The <application>Python-SQLite</application> python module version 2.0.5 or higher.
740		You can download it from
741		<ulink url="http://www.pysqlite.org">http://www.pysqlite.org</ulink>
742		</para>
743		</listitem>
744		</itemizedlist>
745		</para>
746		</listitem>
747		<listitem>
748		<para>
749		Berkeley DB backend : Not supported yet.
750		</para>
751		</listitem>
752		</itemizedlist>
753		</para>
754		</listitem>
755		<listitem>
756		<para>
757		<application>ucd-snmp</application> or <application>net-snmp</application> tools, version 4.2.5 or above. You only need
758		the <command>snmpget</command> command.
759		You can download this software from <ulink url="http://www.sourceforge.net/projects/net-snmp/">http://www.sourceforge.net/projects/net-snmp/</ulink>.
760		You only need this if PyKota's internal SNMP accounting code doesn't work for your SNMP-aware
761		printers.
762		</para>
763		</listitem>
764		<listitem>
765		<para>
766		<application>netatalk</application> version 1.6.1 or above. You only need
767		the <command>pap</command> command.
768		You can download this software from <ulink url="http://netatalk.sourceforge.net/">http://netatalk.sourceforge.net/</ulink>.
769		You only need this if you plan to query your printers for their internal page counter via AppleTalk.
770		</para>
771		</listitem>
772		<listitem>
773		<para>
774		eGenix' mxDateTime Python module version 2.0.3 or above. It must match your default Python version.
775		You can download it from <ulink url="http://www.egenix.com">http://www.egenix.com</ulink>.
776		</para>
777		</listitem>
778		<listitem>
779		<para>
780		The Python acccelerator <application>Psyco</application>. It must match your default Python version.
781		You can download it from <ulink url="http://psyco.sourceforge.net">http://psyco.sourceforge.net</ulink>.
782		You only need this if you run on the <literal>x86</literal> architecture because
783		<application>Psyco</application> doesn't yet exist on other architectures.
784		</para>
785		</listitem>
786		<listitem>
787		<para>
788		The <application>pysnmp</application> Python module version 3.4.2, or higher, version 4 is recommanded.
789		You can download it from <ulink url="http://pysnmp.sourceforge.net">http://pysnmp.sourceforge.net</ulink>.
790		</para>
791		</listitem>
792		<listitem>
793		<para>
794		The <application>JAXML</application> Python module.
795		You can download it from <ulink url="http://www.librelogiciel.com/software/">http://www.librelogiciel.com/software/</ulink>.
796		</para>
797		</listitem>
798		<listitem>
799		<para>
800		The <application>ReportLab</application> Toolkit Python module.
801		You can download it from <ulink url="http://www.reportlab.org">http://www.reportlab.org</ulink>.
802		</para>
803		</listitem>
804		<listitem>
805		<para>
806		The <application>Python Imaging Library - PIL</application> module.
807		You can download it from <ulink url="http://www.pythonware.com">http://www.pythonware.com</ulink>.
808		</para>
809		</listitem>
810		<listitem>
811		<para>
812		The <application>PyOSD</application> Python module.
813		You can download it from <ulink url="http://repose.cx/pyosd/">http://repose.cx/pyosd/</ulink>.
814		</para>
815		</listitem>
816		<listitem>
817		<para>
818		The <application>pkpgcounter</application> Generic Page Description Language parser.
819		You can download it from <ulink url="http://www.pykota.com.com/software/pkpgcounter">http://www.pykota.com/software/pkpgcounter</ulink>.
820		</para>
821		</listitem>
822		<listitem>
823		<para>
824		The <application>PyPAM</application> Python interface to <acronym>PAM</acronym>.
825		You'll need this if you plan to ask users to authenticate when printing through <command>pknotify</command>
826		and <command>pykoticon</command>. You don't need this module otherwise.
827		If needed, you can download it from <ulink url="http://www.pangalactic.org/PyPAM/">http://www.pangalactic.org/PyPAM/</ulink>.
828		</para>
829		</listitem>
830		<listitem>
831		<para>
832		The <application>PkIPPLib</application> Python <acronym>IPP</acronym> library.
833		You can download it from <ulink url="http://www.pykota.com/software/pkipplib">http://www.pykota.com/software/pkipplib</ulink>.
834		</para>
835		</listitem>
836		</itemizedlist>
837		</para>
838
839		<para>
840		Instead of downloading all these programs' sources and compiling them, which really
841		is a boring task considering that many software are needed, you may prefer to look
842		into the packages included with your GNU/Linux distribution of choice (if you use
843		this operating system of course). Most, if not all, GNU/Linux distributions include
844		all the software mentionned above, in the form of packages which are easier to
845		install than sources tarballs. This is probably the same for the many *BSD
846		distributions.
847		</para>
848
849		<para>
850		You can check that all needed software is installed by launching the <command>checkdeps.py</command>
851		command :
852		<screen>
853		$ python checkdeps.py
854		</screen>
855		</para>
856
857		<para>
858		Once all these software are installed, installing PyKota itself is a breeze.
859		PyKota being written entirely in the Python language, which is interpreted,
860		there's no need to compile anything. You just have to execute the installation
861		script :
862		<screen>
863		$ python setup.py install
864		</screen>
865		</para>
866
867		<para>
868		The setup script will automatically create the
869		<filename>/usr/share/pykota/conf</filename> directory and put the sample
870		configuration files <filename>conf/pykota.conf.sample</filename> and
871		<filename>conf/pykotadmin.conf.sample</filename> there, along with
872		a <filename>README</filename> file explaining their purpose.
873		</para>
874
875		<para>
876		Now you have to create a <literal>pykota</literal> system user and group. The <application>PyKota</application>
877		software will automatically search its configuration files in user <literal>pykota</literal>'s
878		home directory. For example we could create the user and group, and set <filename>/etc/pykota</filename>
879		as the home directory, but any other home directory will do :
880		<screen>
881		adduser --system --group --home /etc/pykota --gecos PyKota pykota
882		</screen>
883		</para>
884
885		<para>
886		You now have to copy the sample configuration files into the <filename>~pykota</filename>
887		directory, under the respective names <filename>pykota.conf</filename> and
888		<filename>pykotadmin.conf</filename>. Once copied there, you just
889		have to modify these files to adapt them to your own setup.
890		These files are heavily commented, so you should have no problem.
891		Also their format is quite common, because it's the one used by
892		<application>Samba</application> for example, or by <literal>.ini</literal>
893		files under <application>MS-Windows</application>, so you may already
894		be familiar with this syntax.
895		In a future release, this documentation will include the complete
896		reference for all configuration fields available. Keep in mind that
897		<application>PyKota</application> can be really heavily customized, and can delegate some work
898		to any external command of your choice.
899		</para>
900
901		<para>
902		Please create a backup copy of the <filename>~pykota</filename>
903		directory before modifying a working installation.
904		</para>
905
906		<para>
907		PyKota features some interesting possibilities which allow you to
908		define options either globally so that they apply to all printers,
909		or on a per printer basis. Please see the sample configuration files
910		to see what I mean. In the simplest form, only a <literal>[global]</literal> section is
911		needed. In more complex configurations, you will have to create
912		one section per printer. Each section in the configuration files
913		begins with a name between square brackets <literal>[]</literal>.
914		The name to use to define a particular printer section is the name
915		of the print queue you want to manage with PyKota.
916		</para>
917
918		<para>
919		After you have modified <application>PyKota</application>'s configuration files, you have to
920		double check their permissions, otherwise your installation may be
921		insecure or may not work at all.
922		The main configuration file <filename>~pykota/pykota.conf</filename>
923		doesn't contain much sensitive information, so it can be made
924		readable by anyone. If normal users read this file, at best they
925		will learn the username and optional password of the read-only
926		database user. This means that beside being allowed to read all the contents of
927		the quota database, they won't be allowed to modify or delete it.
928		On the other hand, the <filename>~pykota/pykotadmin.conf</filename>
929		file contains the read-write user's identity and password. You must then
930		ensure that no normal user can read this file. It should only be readable
931		by the <literal>root</literal> user, which is always the case, and by
932		<application>PyKota</application> administrators. In addition,
933		users for which <application>CUPS</application> doesn't run as user <literal>root</literal> will
934		have to ensure that the user their printing system is run as
935		can read both of these files. An easy way to do so is to put the <literal>lp</literal> user
936		(for example) into the <literal>pykota</literal> system group, then
937		to give the correct permissions to <application>PyKota</application>'s configuration files :
938		<screen>
939		$ chown -R pykota.pykota ~pykota/
940		$ chmod 750 ~pykota/
941		$ chmod 644 ~pykota/pykota.conf
942		$ chmod 640 ~pykota/pykotadmin.conf
943		</screen>
944
945		<warning>
946		<title>Warning</title>
947		<para>
948		All the users allowed to read the <filename>~pykota/pykotadmin.conf</filename>
949		are considered to be <application>PyKota</application> administrators. So be
950		careful with these files permissions.
951		</para>
952		</warning>
953		</para>
954
955		<para>
956		On some systems, you may be able to strenghten permissions like this :
957		<screen>
958		$ chown -R pykota.pykota ~pykota/
959		$ chmod 750 ~pykota/
960		$ chmod 640 ~pykota/pykota.conf
961		$ chmod 600 ~pykota/pykotadmin.conf
962		</screen>
963		</para>
964
965		<para>
966		And on other ones, you may need to relax them, and change the files' owner :
967		<screen>
968		$ chown pykota.pykota ~pykota/
969		$ chmod 755 ~pykota/
970		$ chown lp.pykota ~pykota/pykota.conf
971		$ chmod 640 ~pykota/pykota.conf
972		$ chown lp.pykota ~pykota/pykotadmin.conf
973		$ chmod 640 ~pykota/pykotadmin.conf
974		</screen>
975		</para>
976
977		<para>
978		This all depends on the printing system you are using, and the user the
979		printing system is usually running as. You need to remember three things :
980
981		<itemizedlist>
982		<listitem>
983		<para>
984		The user your printing system runs as MUST be allowed to read
985		both <application>PyKota</application>'s configuration files.
986		</para>
987		</listitem>
988		<listitem>
989		<para>
990		Any user who can read <filename>pykotadmin.conf</filename>
991		is a <application>PyKota</application> administrator, and
992		can do whatever he wants to the print quota database.
993		</para>
994		</listitem>
995		<listitem>
996		<para>
997		If <filename>cupsd.conf</filename> contains <literal>RunAsUser</literal>, then
998		you won't be able to authenticate users with <command>pknotify</command> and <command>pykoticon</command>.
999		Also in this case you may have to make <application>PyKota</application>'s configuration files
1000		owned by the user <application>CUPS</application> runs as.
1001		</para>
1002		</listitem>
1003		</itemizedlist>
1004		</para>
1005
1006		<para>
1007		Don't forget to restart your print server sofware if you changed group membership for the user it runs
1008		as, otherwise your change wouldn't be taken into account.
1009		</para>
1010
1011		<para>
1012		Now depending on your printing system, the configuration to do is particular.
1013		We will now see how to plug PyKota into <application>CUPS</application> since <application>LPRng</application>
1014		is not supported anymore.
1015		</para>
1016
1017		<sect2>
1018		<title>With CUPS</title>
1019
1020		<para>
1021		From version 1.16alpha7 on, configuring <application>PyKota</application> to integrate
1022		within <application>CUPS</application> is more than easy.
1023		</para>
1024
1025		<para>
1026		You just have to create a symbolic link to the <command>cupspykota</command>
1027		command in <application>CUPS</application>' backend directory :
1028		<screen>
1029		$ cd /usr/lib/cups/backend
1030		$ ln -s /usr/share/pykota/cupspykota cupspykota
1031		</screen>
1032		</para>
1033
1034		<para>
1035		If you use CUPS v1.2 or higher, you must
1036		also type the following command to allow the <command>cupspykota</command>
1037		backend to correctly support other backends which must be run
1038		as the root user (e.g. the <command>lpd</command> backend) :
1039		<screen>
1040		$ chmod 700 /usr/share/pykota/cupspykota
1041		</screen>
1042		</para>
1043
1044		<para>
1045		You have to restart <application>CUPS</application> for this modification to
1046		take effect :
1047		<screen>
1048		$ /etc/init.d/cupsys restart
1049		</screen>
1050		</para>
1051
1052		<para>
1053		Now point your web browser to CUPS configuration page, usually at
1054		<ulink url="http://localhost:631">http://localhost:631</ulink> on
1055		your print server.
1056		</para>
1057
1058		<para>
1059		Then when creating new printers or reconfiguring existing ones, just
1060		choose devices which are <literal>PyKota managed</literal>
1061		<footnote>
1062		<para>
1063		Debian 3.0 Woody is known to have problems : CUPS 1.1.14 doesn't automatically
1064		detect <literal>PyKota managed</literal> devices. So you have to manually
1065		modify CUPS' <filename>printers.conf</filename> file as explained in
1066		PyKota's toplevel <filename>README</filename> file.
1067		</para>
1068		</footnote>
1069		instead of
1070		normal devices. You've got one <literal>PyKota managed</literal> device
1071		for each regular device available from CUPS, so just choose the appropriate
1072		one.
1073		</para>
1074
1075		<para>
1076		Repeat the above procedure for each print queue on which you want to use
1077		PyKota. That's all !
1078		</para>
1079
1080		<sect3>
1081		<title>Troubleshooting</title>
1082		<para>
1083		In case of problem, the simplest way to solve it is currently
1084		to ask on PyKota's mailing list, describing the symptoms, as
1085		well as the hardware and software you use.
1086		</para>
1087
1088		<para>
1089		A searchable FAQ is now available at
1090		<ulink url="http://otrs.librelogiciel.com/otrs/public.pl">http://otrs.librelogiciel.com/public.pl</ulink>.
1091		A FAQ entry explaining in great details how to diagnose a problem correctly is
1092		available at
1093		<ulink url="http://otrs.librelogiciel.com/otrs/public.pl?ID=2">http://otrs.librelogiciel.com/public.pl?ID=2</ulink>.
1094		</para>
1095
1096		<para>
1097		You can also ask questions on IRC :
1098		<screen>
1099		/server irc.freenode.net
1100		/join #pykota
1101		</screen>
1102		</para>
1103		</sect3>
1104
1105		</sect2>
1106
1107		</sect1>
	1144	</sect1>
1108	1145	</chapter>
1109	1146

pykota/trunk/docs/introduction.sgml

r2909	r3116
46	46	it will mandate that you also install several dependencies beforehand, as you'll see in the
47	47	next chapter.
48		~~</para>~~
49
50		~~<para>~~
51		~~Beginning on October 10th 2005, this document won't be <application>PyKota</application>'s reference documentation anymore.~~
52		~~<application>PyKota</application>'s reference documentation is now at :~~
53		~~<ulink url="http://www.pykota.com/wiki">http://www.pykota.com/wiki</ulink>~~
54	48	</para>
55	49
…	…
129	123	<listitem>
130	124	<para>
	125	<command>pksetup</command> : to install PyKota in a completely
	126	interactive way, but currently only under Debian and Ubuntu.
	127	</para>
	128	</listitem>
	129	<listitem>
	130	<para>
131	131	<command>pkturnkey</command> : to help you do the initial
132	132	configuration and database initialization. This command almost transforms <application>PyKota</application>
…	…
225	225	</para>
226	226	</listitem>
	227	<listitem>
	228	<para>
	229	<command>pkrefund</command> : a tool with which you can refund print jobs
	230	when there was an accounting problem. It can generate printable receipts
	231	in the PDF format.
	232	</para>
	233	</listitem>
227	234	</itemizedlist>
228	235	</para>

Context Navigation

Changeset 3116

Legend:

pykota/trunk/docs/installation.sgml

pykota/trunk/docs/introduction.sgml

Download in other formats: