Changeset 3413 for pykota/trunk/docs

pykota/trunk/docs/autopykota.sgml

r2147	r3413
4	4	<title>Automate user account creation with autopykota</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	If you want to automate the users account and quota entries creation on first print,
…	…
11	11	You just have to put your command of choice there.
12	12	</para>
13
	13
14	14	<para>
15	15	<command>autopykota</command> was designed to automatically set
16	16	an initial account balance value to newly added users, while taking
17		care of not resetting the balance value if the user already exists
18		but doesn't have a quota entry on the current printer.
	17	care of not resetting the balance value if the user already exists
	18	but doesn't have a quota entry on the current printer.
19	19	</para>
20
	20
21	21	<para>
22	22	If you want to limit your users by page quota then you must not use
…	…
30	30	care of all this automagically.
31	31	</para>
32
	32
33	33	<sect1>
34	34	<title>Reference</title>

pykota/trunk/docs/dumpykota.sgml

r2551	r3413
4	4	<title>Export datas to other software with dumpykota</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	If you want to reuse <application>PyKota</application> datas from another
…	…
11	11	best option is the new <command>dumpykota</command> command.
12	12	</para>
13
	13
14	14	<para>
15	15	<command>dumpykota</command> can export <application>PyKota</application>
16	16	datas in a number of formats. The supported output formats are
17	17	comma separated values, semicolon separated values, tab separated values, and <acronym>XML</acronym>.
18		</para>
19
	18	</para>
	19
20	20	<para>
21	21	For the print job history's datas, a special format identical to <application>CUPS</application>' <literal>page_log</literal>
…	…
23	23	This allows you to interface <application>PyKota</application> with third party tools like
24	24	<application>phpPrintAnalyzer</application> which is a logfile analyzer for <application>CUPS</application>.
25		</para>
26
	25	</para>
	26
27	27	<para>
28		More formats may be added in the future. In particular,
29		<acronym>SQL</acronym> and <acronym>LDIF</acronym> are planned, but
30		are currently not implemented.
	28	More formats may be added in the future. In particular,
	29	<acronym>SQL</acronym> and <acronym>LDIF</acronym> are planned, but
	30	are currently not implemented.
31	31	</para>
32
	32
33	33	<para>
34	34	<command>dumpykota</command> can't dump all datas at once though, you have
…	…
44	44	<listitem><para>History of payments</para></listitem>
45	45	<listitem><para>History of print jobs</para></listitem>
46		</itemizedlist>
	46	</itemizedlist>
47	47	</para>
48
	48
49	49	<para>
50		You can then import the dumped datas into a spreadsheet for example,
	50	You can then import the dumped datas into a spreadsheet for example,
51	51	if you want to create complex reports with nice looking graphs and
52	52	the like.
53	53	</para>
54
	54
55	55	<para>
56	56	An important feature of this command is the possibility to use
…	…
64	64	the year <literal>2005</literal>.
65	65	</para>
66
	66
67	67	<para>
68	68	Several keys like <literal>username</literal> are possible, but some
…	…
74	74	the complete list of supported keys.
75	75	</para>
76		</tip>
	76	</tip>
77	77	</para>
78
	78
79	79	<para>
80	80	This command could also be used if you plan to write your own management
…	…
85	85	This is exactly what the third party software <application>phpPykotaAdmin</application> does.
86	86	</para>
87
	87
88	88	<para>
89	89	Finally, <command>dumpykota</command>'s functionnality is now also available remotely through
90	90	the use of the <command>dumpykota.cgi</command> <acronym>CGI</acronym> script.
91	91	</para>
92
	92
93	93	<warning>
94	94	<title>Warning</title>
…	…
96	96	Only <application>PyKota</application> administrators can dump PyKota's datas.
97	97	</para>
98		</warning>
99
	98	</warning>
	99
100	100	<sect1>
101	101	<title>Reference</title>

pykota/trunk/docs/edpykota.sgml

r2833	r3413
4	4	<title id="edpykota">Manage Print Quotas with edpykota</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	You'll use this tool to create, manage or delete print quota entries for users
9	9	or users groups on printers or printers groups.
10	10	</para>
11
	11
12	12	<para>
13	13	By default, before being allowed to print through <application>PyKota</application>,
…	…
15	15	he should be allowed to use. As seen in the previous chapter, the simplest way to add an user named <literal>jerome</literal> to the database is
16	16	to type :
17		<screen>
	17	<screen>
18	18	$ pkusers --add jerome
19	19	</screen>
…	…
21	21	But this is not sufficient to allow user <literal>jerome</literal> to print. You have to create a print quota entry for <literal>jerome</literal> on all printers
22	22	he is allowed to print to. The easiest way to do so is to type :
23		<screen>
	23	<screen>
24	24	$ edpykota --add jerome
25	25	</screen>
26	26	</para>
27
	27
28	28	<para>
29	29	The commands above have created user <literal>jerome</literal> in the database, and have automatically
…	…
32	32	will still be done for this user : you'll know whenever he prints and how much.
33	33	</para>
34
	34
35	35	<para>
36	36	Here's an incomplete list of features :
37
	37
38	38	<itemizedlist>
39	39	<listitem>
…	…
59	59	</itemizedlist>
60	60	</para>
61
	61
62	62	<para>
63	63	For more details on the use of <command>edpykota</command>, please see this command's manual
64	64	page or help.
65	65	</para>
66
	66
67	67	</chapter>
68	68

pykota/trunk/docs/filterpykota.sgml

r2835	r3413
3	3	<chapter>
4	4	<title id="filter">PyKota's internals</title>
5
	5
6	6	<para>Last modified on $Date: 2005-03-06 17:52:43 +0100 (dim, 06 mar 2005) $</para>
7
	7
8	8	<para>
9		To account for pages or eventually ink usage
	9	To account for pages or eventually ink usage
10	10	<footnote>
11	11	<para>
12	12	PyKota doesn't currently account for ink usage, it only accounts
13	13	pages. To account for ink usage, you should use PrintBill instead for now.
14		</para>
15		</footnote>
	14	</para>
	15	</footnote>
16	16	, you must plug your accounting
17	17	system somewhere into the printing system you use. One way to do this without having
18	18	to modify the printing system itself, is by using a <firstterm>filter</firstterm>.
19	19	</para>
20
	20
21	21	<para>
22	22	A filter is a computer program which takes data in one format as its input, and outputs the
23	23	same data but transformed into another format. <application>CUPS</application> already
24		contains many filters. For example there's one filter named <command>pstops</command> which accepts
	24	contains many filters. For example there's one filter named <command>pstops</command> which accepts
25	25	PostScript data as its input, and, as its name implies, outputs PostScript data too, but after having
26	26	eventually rearranged the pages to fit several pages on a single sheet of paper, or other manipulations
27	27	like that.
28	28	</para>
29
	29
30	30	<para>
31	31	The <command>pstops</command> filter described above is also in charge of doing basic page
…	…
33	33	prove to be unreliable depending on the drivers used or if a paper jam occurs for example.
34	34	</para>
35
	35
36	36	<para>
37	37	So to do its own accounting, <application>PyKota</application> has its own filters, for <application>CUPS</application>
38	38	it's named <command>cupspykota</command>, which is in fact a <application>CUPS</application> backends wrapper.
39		The procedure to plug the correct filter into your printing system is described in the
	39	The procedure to plug the correct filter into your printing system is described in the
40	40	<xref linkend="installation" endterm="installation"> chapter.
41	41	</para>
42
	42
43	43	<para>
44	44	Currently with <application>CUPS</application>' internal accounting mechanism, the <command>pstops</command>
…	…
48	48	print job will be correctly accounted for.
49	49	</para>
50
	50
51	51	<para>
52	52	When using the <literal>hardware</literal> accounting method,
53	53	<application>PyKota</application> launches the script you specified to
54	54	ask the printer for its internal page counter at the start and at the end of the print job, and
55		computes the values' difference to know the job's size.
	55	computes the values' difference to know the job's size.
56	56	</para>
57
	57
58	58	<para>
59	59	When using the <literal>software</literal> accounting method,
60		the command you specified is launched with the job's data on its
	60	the command you specified is launched with the job's data on its
61	61	standard input. Your command must print the job's size in number of
62	62	pages on a single line on its standard output. This number is then
63	63	read by <application>PyKota</application> and used to update the current user's quota information.
64	64	</para>
65
	65
66	66	<para>
67	67	If a problem occurs, it is logged either to the filter's standard error or to the system logger, depending on
…	…
71	71	messages if you want.
72	72	</para>
73
	73
74	74	</chapter>
75	75

pykota/trunk/docs/installation.sgml

r3283	r3413
3	3	<chapter>
4	4	<title id="installation">Installation</title>
5
	5
6	6	<para>Last modified on $Date$</para>
7
	7
8	8	<para>
9	9	Before being able to use <application>PyKota</application>, you have of course to
10	10	install it first. But before installing, you must carefully plan your installation.
11	11	</para>
12
	12
13	13	<para>
14	14	First you have to determine which machine will be the <application>PyKota</application>
…	…
16	16	for keeping a centralized database of print usage for all your printers, users and groups.
17	17	</para>
18
	18
19	19	<para>
20	20	Then you have to list all the <firstterm>Print Servers</firstterm> for which
21	21	you plan to use print quota facilities.
22	22	</para>
23
	23
24	24	<para>
25	25	With most database backends, several print servers can share a single database, however
…	…
27	27	as your print quota database backend.
28	28	</para>
29
	29
30	30	<para>
31	31	Finally you have to download <application>PyKota</application>'s latest version
32		or buy an official package, from
	32	or buy an official package, from
33	33	<ulink url="http://www.pykota.com/software/pykota">http://www.pykota.com/software/pykota</ulink>.
34	34	If you've just bought an official package, then as soon as you've receive it you
35	35	have to decompress and visit its archive, to do so just type the following commands :
36	36	<screen>
37		jerome@nordine:~$ tar -zxf pykota-1.26_official.tar.gz
	37	jerome@nordine:~$ tar -zxf pykota-1.26_official.tar.gz
38	38	jerome@nordine:~$ cd pykota-1.26_official
39	39	jerome@nordine:~/pykota-1.26_official$
40	40	</screen>
41	41	</para>
42
	42
43	43	<para>
44	44	You can see many files in this directory, the first ones to read are <filename>README</filename>,
45	45	then <filename>COPYING</filename> and <filename>LICENSE</filename>. They will give you
46		basic installation instructions and explain the licensing terms under which
	46	basic installation instructions and explain the licensing terms under which
47	47	<application>PyKota</application> is distributed. Of course they are also mostly
48	48	boring to read ! Detailed installation and operating instructions are defined
…	…
54	54	know this because that's what you are currently reading !
55	55	</para>
56
	56
57	57	<sect1>
58	58	<title>Interactive step-by-step installation of PyKota with pksetup</title>
59
	59
60	60	<para>
61	61	<command>pksetup</command> is a command line tool with which you'll be able
…	…
66	66	several servers to install identically.
67	67	</para>
68
	68
69	69	<para>
70	70	Currently, <command>pksetup</command> is experimental, and only works
71		with <ulink url="http://www.debian.org">Debian</ulink> and
	71	with <ulink url="http://www.debian.org">Debian</ulink> and
72	72	<ulink url="http://www.ubuntu.com">Ubuntu</ulink> distributions.
73	73	In addition, the database backend which will be installed with
…	…
77	77	the installation manually, then read and follow the instructions in the next section.
78	78	</para>
79
	79
80	80	<para>
81	81	To launch the installation procedure, just type <literal>pksetup</literal>
82	82	followed with the name of your distribution, like :
83		<screen>
	83	<screen>
84	84	jerome@nordine:~/pykota-1.26_official$ ./bin/pksetup debian
85		</screen>
	85	</screen>
86	86	and then follow the instructions and answer to the several questions you'll
87	87	be asked.
88	88	</para>
89	89	</sect1>
90
	90
91	91	<sect1>
92	92	<title>Manual installation</title>
…	…
100	100	This is especially the case if you've got only one server.
101	101	</para>
102		</note>
	102	</note>
103	103	</para>
104
	104
105	105	<sect2>
106	106	<title>Database server installation</title>
107
	107
108	108	<para>
109	109	Depending on <application>PyKota</application>'s version number, different
…	…
111	111	them how to configure it.
112	112	</para>
113
	113
114	114	<sect3>
115	115	<title>PostgreSQL</title>
116
	116
117	117	<para>
118	118	<application>PostgreSQL</application> is an <firstterm>Object Relationnal DataBase
119	119	Management System</firstterm> distributed under a <firstterm>Free Software</firstterm>
120		license from the
	120	license from the
121	121	<ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink>
122	122	web site. It certainely is the free <acronym>RDBMS</acronym> which has the most advanced
123	123	features, and is widely used all over the world.
124	124	</para>
125
	125
126	126	<para>
127	127	To configure your database, you must have PostgreSQL already working.
128	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
	129	the present manual, please refer to your system's documentation or to
130	130	<ulink url="http://www.postgresql.org">http://www.postgresql.org</ulink> for
131	131	details.
132	132	</para>
133
	133
134	134	<para>
135	135	One thing you have to check, though, is that every Print Server on which you
…	…
146	146	is not necessary though if your print quota database server and your Print Server are
147	147	the very same host.
148		</para>
149
	148	</para>
	149
150	150	<para>
151	151	Here's an excerpt from a <filename>pg_hba.conf</filename> file. This one rejects all
152	152	connections to PyKota's database excepted when made from the same host by <application>PostgreSQL</application> users
153	153	<literal>pykotauser</literal> or <literal>pykotaadmin</literal> with the correct password.
154		<screen>
	154	<screen>
155	155	local all postgres ident sameuser
156	156	local all all reject
…	…
160	160	</screen>
161	161	</para>
162
	162
163	163	<para>
164	164	Of course if your print server and your database servers have different <acronym>IP</acronym>
…	…
173	173	any of its configuration files, in order for the changes to take effect.
174	174	</para>
175		</tip>
176		</para>
177
	175	</tip>
	176	</para>
	177
178	178	<para>
179	179	Be careful, you may be unable to connect from a Print Server to the <application>PostgreSQL</application>
…	…
186	186	<title>Note</title>
187	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
	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	194	<para>
195	195	Now that your <application>PostgreSQL</application> server is up and running, and
…	…
203	203	itself, he is only defined in <application>PostgreSQL</application> and don't
204	204	have to exist on any system, nor in the print quota database. His default name
205		is <literal>pykotaadmin</literal>.
	205	is <literal>pykotaadmin</literal>.
206	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
	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	209	<footnote><para>a <application>PyKota</application> administrator is an user who can read the <filename>~pykota/pykotadmin.conf</filename> file.</para></footnote>
210	210	launches a pykota command. This prevents normal
…	…
217	217	<title>Note</title>
218	218	<para>
219		You can choose other names and passwords if you want by modifying the
	219	You can choose other names and passwords if you want by modifying the
220	220	<filename>initscripts/postgresql/pykota-postgresql.sql</filename> file
221	221	accordingly, and report your changes into <application>PyKota</application>'s
222	222	configuration files.
223	223	</para>
224		</note>
225		</para>
226
	224	</note>
	225	</para>
	226
227	227	<para>
228	228	To run this script, you can use the <command>psql</command> frontend to
…	…
236	236	jerome@nordine:~/pykota-1.26_official/initscripts$ psql -h localhost -U postgres template1
237	237	Welcome to psql, the PostgreSQL interactive terminal.
238
	238
239	239	Type: \copyright for distribution terms
240	240	\h for help with SQL commands
…	…
242	242	\g or terminate with semicolon to execute query
243	243	\q to quit
244
245		template1=# \i pykota-postgresql.sql
	244
	245	template1=# \i pykota-postgresql.sql
246	246	... a lot of output lines
247		pykota=#
	247	pykota=#
248	248	</screen>
249	249	<note>
…	…
252	252	If you use RPM or DEB packages, usually the
253	253	<filename>pykota-postgresql.sql</filename> file gets installed into the
254		<filename>/usr/share/pykota/postgresql</filename> directory, along
	254	<filename>/usr/share/pykota/postgresql</filename> directory, along
255	255	with a README file.
256	256	</para>
257		</note>
258		</para>
259
	257	</note>
	258	</para>
	259
260	260	<para>
261	261	If you want to you can change passwords later in
262		<application>PostgreSQL</application> for the
	262	<application>PostgreSQL</application> for the
263	263	<literal>pykotaadmin</literal> and <literal>pykotauser</literal> users.
264	264	To do so, just type the following lines while still being at the <command>psql</command>
…	…
272	272	</screen>
273	273	</para>
274
	274
275	275	<para>
276	276	The <literal>\q</literal> command above will quit the <command>psql</command>
277	277	program and return you to the shell's command line prompt.
278	278	</para>
279
	279
280	280	<para>
281	281	To improve security further, you could encrypt your database connections, or
282	282	take any other step as needed. Please refer to <application>PostgreSQL</application>'s
283		documentation for details.
	283	documentation for details.
284	284	<warning>
285	285	<title>Warning</title>
…	…
293	293	though, it is just a general rule to keep in mind.
294	294	</para>
295		</warning>
296		</para>
297
	295	</warning>
	296	</para>
	297
298	298	<para>
299	299	For more details, please see <filename>initscripts/mysql/README.postgresql</filename>.
300	300	</para>
301
	301
302	302	<para>
303	303	If no error occured, then your print quota database is ready to be used.
…	…
312	312	can try to fix the problem. Thanks in advance.
313	313	</para>
314		</tip>
315		</para>
316
317		</sect3>
318
	314	</tip>
	315	</para>
	316
	317	</sect3>
	318
319	319	<sect3>
320	320	<title>LDAP</title>
321
322		<para>
323		Any <acronym>LDAP</acronym> server, and particularly <application>OpenLDAP</application>, can be used
	321
	322	<para>
	323	Any <acronym>LDAP</acronym> server, and particularly <application>OpenLDAP</application>, can be used
324	324	as a print quota database backend.
325	325	Some other LDAP servers can be used, but this is currently untested in production.
326	326	</para>
327
	327
328	328	<para>
329	329	<application>OpenLDAP</application> is a Lightweight Directory Access Protocol server
…	…
331	331	You can download it from <ulink url="http://www.openldap.org">http://www.openldap.org</ulink>.
332	332	</para>
333
	333
334	334	<para>
335	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
	336	<filename>pykota/initscripts/ldap/pykota.schema</filename> into <application>OpenLDAP</application>'s
337	337	schemas directory.
338	338	Under Debian GNU/Linux, this is something like :
339		<screen>
	339	<screen>
340	340	$ cp pykota.schema /etc/ldap/schema
341	341	</screen>
…	…
343	343	<title>Note</title>
344	344	<para>
345		If you are using a Red Hat-based system, substitute
346		<filename>/etc/openldap</filename> for
	345	If you are using a Red Hat-based system, substitute
	346	<filename>/etc/openldap</filename> for
347	347	<filename>/etc/ldap</filename>.
348	348	</para>
…	…
357	357	your <acronym>LDAP</acronym> server's schemas directory.
358	358	</para>
359		</note>
	359	</note>
360	360	</para>
361		<para>
362		Then edit <filename>/etc/ldap/slapd.conf</filename> and add a line to
	361	<para>
	362	Then edit <filename>/etc/ldap/slapd.conf</filename> and add a line to
363	363	include the PyKota schema. You should have something
364	364	like :
365		<screen>
	365	<screen>
366	366	# Schema and objectClass definitions
367	367	include /etc/ldap/schema/core.schema
…	…
370	370	include /etc/ldap/schema/inetorgperson.schema
371	371	include /etc/ldap/schema/pykota.schema
372		</screen>
373		</para>
374
	372	</screen>
	373	</para>
	374
375	375	<para>
376	376	While this is not mandatory, it is recommended that you setup
…	…
387	387	</screen>
388	388	</para>
389
390		<para>
391		Now you must ensure that the DNs you'll use to bind to
	389
	390	<para>
	391	Now you must ensure that the DNs you'll use to bind to
392	392	your OpenLDAP server don't have search queries size limits,
393	393	which gives for example (OpenLDAP 2.1.x or above) :
394
395		<screen>
	394
	395	<screen>
396	396	# No Limits for PyKota's administrator and read-only user
397	397	limits dn="cn=pykotaadmin,dc=example,dc=com" size.soft=-1 size.hard=soft
398	398	limits dn="cn=pykotauser,dc=example,dc=com" size.soft=-1 size.hard=soft
399		</screen>
400
	399	</screen>
	400
401	401	Where pykotaadmin and pykotauser are the usernames used to bind to your
402		OpenLDAP server within PyKota, respectively in ReadWrite mode
	402	OpenLDAP server within PyKota, respectively in ReadWrite mode
403	403	(as set in pykotadmin.conf) and in ReadOnly mode (as set in pykota.conf).
404	404	</para>
405
	405
406	406	<para>
407	407	Finally, stop the <application>OpenLDAP</application> server, generate
408	408	the index files, and restart <application>OpenLDAP</application>
409		<screen>
	409	<screen>
410	410	$ /etc/init.d/slapd stop
411	411	$ slapindex
…	…
416	416	<title>Note</title>
417	417	<para>
418		On Red Hat-based distros, use '/sbin/service ldap stop' and
	418	On Red Hat-based distros, use '/sbin/service ldap stop' and
419	419	'/sbin/service ldap start' instead.
420	420	</para>
…	…
430	430	entries, this may ease the maintainance.
431	431	</para>
432
	432
433	433	<para>
434	434	PyKota needs at least an <literal>ou</literal> for printers, for users quotas, for
…	…
437	437	will probably be attached to each printer.
438	438	</para>
439
	439
440	440	<para>
441	441	Actually PyKota doesn't create these <literal>ou</literal>s for you, because it's
…	…
450	450	If you use RPM or DEB packages, usually the
451	451	<filename>pykota-sample.ldif</filename> file is installed into the
452		<filename>/usr/share/pykota/ldap</filename> directory, along
	452	<filename>/usr/share/pykota/ldap</filename> directory, along
453	453	with a README file.
454	454	</para>
455		</note>
456		</para>
457
	455	</note>
	456	</para>
	457
458	458	<para>
459	459	If no error occured, then your print quota database is ready to be used.
…	…
468	468	can try to fix the problem. Thanks in advance.
469	469	</para>
470		</tip>
471		</para>
472		</sect3>
473
	470	</tip>
	471	</para>
	472	</sect3>
	473
474	474	<sect3>
475	475	<title>MySQL</title>
476
	476
477	477	<para>
478	478	<application>MySQL</application> is a simple Relationnal DataBase
479	479	Management System distributed under a <firstterm>Free Software</firstterm>
480		license from the
	480	license from the
481	481	<ulink url="http://www.mysql.org">http://www.mysql.org</ulink>
482		web site.
483		</para>
484
	482	web site.
	483	</para>
	484
485	485	<para>
486	486	To configure your database, you must have MySQL version 4.1 or higher already working.
487	487	We recommend that you use MySQL 5.0 or higher though.
488	488	The complete installation of <application>MySQL</application> is not covered by
489		the present manual, please refer to your system's documentation or to
	489	the present manual, please refer to your system's documentation or to
490	490	<ulink url="http://www.mysql.org">http://www.mysql.org</ulink> for
491	491	details.
492	492	</para>
493
	493
494	494	<para>
495	495	One thing you have to check, though, is that every Print Server on which you
…	…
506	506	any of its configuration files, in order for the changes to take effect.
507	507	</para>
508		</tip>
509		</para>
510
	508	</tip>
	509	</para>
	510
511	511	<para>
512	512	Be careful, you may be unable to connect from a Print Server to the <application>MySQL</application>
…	…
519	519	<title>Note</title>
520	520	<para>
521		The TCP/IP network port used by MySQL may be different. When in doubt, ask your
522		<firstterm>System Administrator</firstterm> for the correct value.
523		</para>
524		</note>
525		</para>
526
	521	The TCP/IP network port used by MySQL may be different. When in doubt, ask your
	522	<firstterm>System Administrator</firstterm> for the correct value.
	523	</para>
	524	</note>
	525	</para>
	526
527	527	<para>
528	528	Now that your <application>MySQL</application> server is up and running, and
…	…
531	531	<filename>pykota-1.26_official/initscripts/mysql/pykota-mysql.sql</filename> file.
532	532	This file will create an empty
533		print quota database and set some permissions on it.
	533	print quota database and set some permissions on it.
534	534	The database which will be created will be named <literal>pykota</literal> by default.
535	535	Two database users will be defined to have access in readonly and read+write modes under
…	…
541	541	<title>Note</title>
542	542	<para>
543		You can choose other names and passwords if you want by modifying the
	543	You can choose other names and passwords if you want by modifying the
544	544	<filename>initscripts/mysql/pykota-mysql.sql</filename> file
545	545	accordingly, and report your changes into <application>PyKota</application>'s
546	546	configuration files.
547	547	</para>
548		</note>
549		</para>
550
	548	</note>
	549	</para>
	550
551	551	<para>
552	552	To run this script, you can use the <command>mysql</command> frontend to
…	…
564	564	If you use RPM or DEB packages, usually the
565	565	<filename>pykota-mysql.sql</filename> file gets installed into the
566		<filename>/usr/share/pykota/mysql</filename> directory, along
	566	<filename>/usr/share/pykota/mysql</filename> directory, along
567	567	with a README file.
568	568	</para>
569		</note>
570		</para>
571
	569	</note>
	570	</para>
	571
572	572	<para>
573	573	To improve security further, you could encrypt your database connections, or
574	574	take any other step as needed. Please refer to <application>MySQL</application>'s
575		documentation for details.
576		</para>
577
	575	documentation for details.
	576	</para>
	577
578	578	<para>
579	579	For more details, please see <filename>initscripts/mysql/README.mysql</filename>.
580	580	</para>
581
	581
582	582	<para>
583	583	If no error occured, then your print quota database is ready to be used.
…	…
592	592	can try to fix the problem. Thanks in advance.
593	593	</para>
594		</tip>
595		</para>
596
597		</sect3>
598
	594	</tip>
	595	</para>
	596
	597	</sect3>
	598
599	599	<sect3>
600	600	<title>SQLite</title>
601
	601
602	602	<para>
603	603	<application>SQLite</application> is an embeddable Relationnal DataBase
604	604	distributed under a Free Software
605		license from the
	605	license from the
606	606	<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink>
607		web site.
	607	web site.
608	608	If is very easy to configure and use, offers a very small memory footprint,
609	609	is very fast, but can only be used on the print server because it doesn't include
610	610	a server daemon : the database is directly embedded in the application.
611	611	</para>
612
	612
613	613	<para>
614	614	To configure your database, you must have SQLite already working.
615	615	The complete installation of <application>SQLite</application> is not covered by
616		the present manual, please refer to your system's documentation or to
	616	the present manual, please refer to your system's documentation or to
617	617	<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink> for
618	618	details.
619	619	</para>
620
	620
621	621	<para>
622	622	Once <application>SQLite</application> is installed, you have to decide where
623	623	you'll put your database. A good idea is to store it into the <literal>pykota</literal>
624	624	user's home directory. Then to create the database, just type :
625		<screen>
	625	<screen>
626	626	# sqlite3 ~pykota/pykota.db <pykota/initscripts/sqlite/pykota.sqlite
627	627	# chown pykota.pykota ~pykota/pykota.db
…	…
634	634	follow the instructions a bit below which explain how to install PyKota on the print server.
635	635	</para>
636
	636
637	637	<para>
638	638	Once this is done, you'll want to set in <filename>~pykota/pykota.conf</filename> the
639	639	following lines in the <literal>[global]</literal> section :
640		<screen>
	640	<screen>
641	641	storagebackend : sqlitestorage
642	642	storagename : /etc/pykota/pykota.db
…	…
657	657	can try to fix the problem. Thanks in advance.
658	658	</para>
659		</tip>
660		</para>
661		</sect3>
662
	659	</tip>
	660	</para>
	661	</sect3>
	662
663	663	<sect3>
664	664	<title>Berkeley DB</title>
665
	665
666	666	<para>
667	667	A <application>Berkeley DB</application> backend is planned, but it actually
…	…
670	670	each print server. This may still prove to be useful for small configurations.
671	671	</para>
672		</sect3>
673		</sect2>
674
	672	</sect3>
	673	</sect2>
	674
675	675	<sect2>
676	676	<title>Print Server Installation</title>
677
	677
678	678	<para>
679	679	For each Print Server on which you plan to implement the print quota
680		mechanism, you have, of course, to have an already working printing environment.
681		Currently <application>PyKota</application> works with
	680	mechanism, you have, of course, to have an already working printing environment.
	681	Currently <application>PyKota</application> works with
682	682	<ulink url="http://www.cups.org"><application>CUPS</application></ulink>
683	683	but older releases also supported <ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>.
684	684	<application>LPRng</application> support might be re-added in the future.
685	685	</para>
686
	686
687	687	<para>
688	688	Here's the list of software you have to install on each Print Server, version numbers
689		are given as an indication of which was successfully tested, but older versions may
	689	are given as an indication of which was successfully tested, but older versions may
690	690	work too.
691	691	<itemizedlist>
692	692	<listitem>
693	693	<para>
694		<application>CUPS</application> version 1.3.4 or higher. NB :
	694	<application>CUPS</application> version 1.3.4 or higher. NB :
695	695	<application>PyKota</application> releases up to and including 1.26 support
696		<application>CUPS</application> version 1.1.14 or higher.
	696	<application>CUPS</application> version 1.1.14 or higher.
697	697	You can download it from <ulink url="http://www.cups.org">http://www.cups.org</ulink>
698	698	</para>
699		</listitem>
	699	</listitem>
700	700	<listitem>
701	701	<para>
…	…
707	707	of this language.
708	708	</para>
709		</listitem>
	709	</listitem>
710	710	<listitem>
711	711	<para>
…	…
721	721	version used on your print quota database server.
722	722	</para>
723		</listitem>
	723	</listitem>
724	724	<listitem>
725	725	<para>
726		The <application>PygreSQL</application> python module.
	726	The <application>PygreSQL</application> python module.
727	727	<application>PygreSQL</application> is normally included in
728	728	<application>PostgreSQL</application>, but you may want to
729	729	download it from <ulink url="http://www.pygresql.org">http://www.pygresql.org</ulink>
730	730	</para>
731		</listitem>
732		</itemizedlist>
	731	</listitem>
	732	</itemizedlist>
733	733	</para>
734		</listitem>
	734	</listitem>
735	735	<listitem>
736	736	<para>
737		OpenLDAP backend :
	737	OpenLDAP backend :
738	738	<itemizedlist>
739	739	<listitem>
…	…
742	742	the <application>OpenLDAP</application> version used on your print quota database server.
743	743	</para>
744		</listitem>
	744	</listitem>
745	745	<listitem>
746	746	<para>
…	…
748	748	You may download this module from <ulink url="http://python-ldap.sourceforge.net">http://python-ldap.sourceforge.net</ulink>
749	749	</para>
750		</listitem>
	750	</listitem>
751	751	</itemizedlist>
752	752	</para>
…	…
761	761	version used on your database server.
762	762	</para>
763		</listitem>
	763	</listitem>
764	764	<listitem>
765	765	<para>
766		The <application>Python-MySQL</application> python module, version 1.2.x or higher.
	766	The <application>Python-MySQL</application> python module, version 1.2.x or higher.
767	767	You can download it from <ulink url="http://sourceforge.net/projects/mysql-python">http://sourceforge.net/projects/mysql-python</ulink>
768	768	</para>
769		</listitem>
770		</itemizedlist>
	769	</listitem>
	770	</itemizedlist>
771	771	</para>
772	772	</listitem>
…	…
774	774	<para>
775	775	SQLite backend : SQLite is not a database server, but an embeddable database, so
776		if you want to use it you MUST install SQLite on your print server. With
	776	if you want to use it you MUST install SQLite on your print server. With
777	777	<application>PostgreSQL</application>, <application>MySQL</application> or
778	778	<application>OpenLDAP</application> you can store your datas on a different
…	…
782	782	<para>
783	783	<application>SQLite</application> version 3.2.1 or higher and its library.
784		You can download it from
	784	You can download it from
785	785	<ulink url="http://www.sqlite.org">http://www.sqlite.org</ulink>
786	786	</para>
787		</listitem>
	787	</listitem>
788	788	<listitem>
789	789	<para>
790	790	The <application>Python-SQLite</application> python module version 2.0.5 or higher.
791		You can download it from
	791	You can download it from
792	792	<ulink url="http://www.pysqlite.org">http://www.pysqlite.org</ulink>
793	793	</para>
794		</listitem>
	794	</listitem>
795	795	</itemizedlist>
796	796	</para>
…	…
801	801	</para>
802	802	</listitem>
803		</itemizedlist>
804		</para>
805		</listitem>
	803	</itemizedlist>
	804	</para>
	805	</listitem>
806	806	<listitem>
807	807	<para>
…	…
812	812	printers.
813	813	</para>
814		</listitem>
	814	</listitem>
815	815	<listitem>
816	816	<para>
…	…
820	820	You only need this if you plan to query your printers for their internal page counter via AppleTalk.
821	821	</para>
822		</listitem>
	822	</listitem>
823	823	<listitem>
824	824	<para>
…	…
826	826	You can download it from <ulink url="http://www.egenix.com">http://www.egenix.com</ulink>.
827	827	</para>
828		</listitem>
	828	</listitem>
829	829	<listitem>
830	830	<para>
831	831	The Python acccelerator <application>Psyco</application>. It must match your default Python version.
832	832	You can download it from <ulink url="http://psyco.sourceforge.net">http://psyco.sourceforge.net</ulink>.
833		You only need this if you run on the <literal>x86</literal> architecture because
	833	You only need this if you run on the <literal>x86</literal> architecture because
834	834	<application>Psyco</application> doesn't yet exist on other architectures.
835	835	</para>
836		</listitem>
	836	</listitem>
837	837	<listitem>
838	838	<para>
…	…
840	840	You can download it from <ulink url="http://pysnmp.sourceforge.net">http://pysnmp.sourceforge.net</ulink>.
841	841	</para>
842		</listitem>
843		<listitem>
844		<para>
845		The <application>JAXML</application> Python module.
	842	</listitem>
	843	<listitem>
	844	<para>
	845	The <application>JAXML</application> Python module.
846	846	You can download it from <ulink url="http://www.librelogiciel.com/software/">http://www.librelogiciel.com/software/</ulink>.
847	847	</para>
848		</listitem>
849		<listitem>
850		<para>
851		The <application>ReportLab</application> Toolkit Python module.
	848	</listitem>
	849	<listitem>
	850	<para>
	851	The <application>ReportLab</application> Toolkit Python module.
852	852	You can download it from <ulink url="http://www.reportlab.org">http://www.reportlab.org</ulink>.
853	853	</para>
854		</listitem>
855		<listitem>
856		<para>
857		The <application>Python Imaging Library - PIL</application> module.
	854	</listitem>
	855	<listitem>
	856	<para>
	857	The <application>Python Imaging Library - PIL</application> module.
858	858	You can download it from <ulink url="http://www.pythonware.com">http://www.pythonware.com</ulink>.
859	859	</para>
860		</listitem>
861		<listitem>
862		<para>
863		The <application>PyOSD</application> Python module.
	860	</listitem>
	861	<listitem>
	862	<para>
	863	The <application>PyOSD</application> Python module.
864	864	You can download it from <ulink url="http://repose.cx/pyosd/">http://repose.cx/pyosd/</ulink>.
865	865	</para>
866		</listitem>
867		<listitem>
868		<para>
869		The <application>pkpgcounter</application> Generic Page Description Language parser.
	866	</listitem>
	867	<listitem>
	868	<para>
	869	The <application>pkpgcounter</application> Generic Page Description Language parser.
870	870	You can download it from <ulink url="http://www.pykota.com.com/software/pkpgcounter">http://www.pykota.com/software/pkpgcounter</ulink>.
871	871	</para>
872		</listitem>
	872	</listitem>
873	873	<listitem>
874	874	<para>
…	…
878	878	If needed, you can download it from <ulink url="http://www.pangalactic.org/PyPAM/">http://www.pangalactic.org/PyPAM/</ulink>.
879	879	</para>
880		</listitem>
	880	</listitem>
881	881	<listitem>
882	882	<para>
…	…
884	884	You can download it from <ulink url="http://www.pykota.com/software/pkipplib">http://www.pykota.com/software/pkipplib</ulink>.
885	885	</para>
886		</listitem>
887		</itemizedlist>
888		</para>
889
	886	</listitem>
	887	</itemizedlist>
	888	</para>
	889
890	890	<para>
891	891	Instead of downloading all these programs' sources and compiling them, which really
…	…
897	897	distributions.
898	898	</para>
899
	899
900	900	<para>
901	901	You can check that all needed software is installed by launching the <command>checkdeps.py</command>
902	902	command :
903		<screen>
904		$ python checkdeps.py
	903	<screen>
	904	$ python checkdeps.py
905	905	</screen>
906	906	</para>
907
	907
908	908	<para>
909	909	Once all these software are installed, installing PyKota itself is a breeze.
910		PyKota being written entirely in the Python language, which is interpreted,
	910	PyKota being written entirely in the Python language, which is interpreted,
911	911	there's no need to compile anything. You just have to execute the installation
912	912	script :
913		<screen>
914		$ python setup.py install
	913	<screen>
	914	$ python setup.py install
915	915	</screen>
916	916	</para>
917
918		<para>
919		The setup script will automatically create the
920		<filename>/usr/share/pykota/conf</filename> directory and put the sample
	917
	918	<para>
	919	The setup script will automatically create the
	920	<filename>/usr/share/pykota/conf</filename> directory and put the sample
921	921	configuration files <filename>conf/pykota.conf.sample</filename> and
922	922	<filename>conf/pykotadmin.conf.sample</filename> there, along with
923	923	a <filename>README</filename> file explaining their purpose.
924	924	</para>
925
	925
926	926	<para>
927	927	Now you have to create a <literal>pykota</literal> system user and group. The <application>PyKota</application>
…	…
929	929	home directory. For example we could create the user and group, and set <filename>/etc/pykota</filename>
930	930	as the home directory, but any other home directory will do :
931		<screen>
	931	<screen>
932	932	adduser --system --group --home /etc/pykota --gecos PyKota pykota
933	933	</screen>
934	934	</para>
935
	935
936	936	<para>
937	937	You now have to copy the sample configuration files into the <filename>~pykota</filename>
938		directory, under the respective names <filename>pykota.conf</filename> and
	938	directory, under the respective names <filename>pykota.conf</filename> and
939	939	<filename>pykotadmin.conf</filename>. Once copied there, you just
940	940	have to modify these files to adapt them to your own setup.
…	…
949	949	to any external command of your choice.
950	950	</para>
951
	951
952	952	<para>
953	953	Please create a backup copy of the <filename>~pykota</filename>
954	954	directory before modifying a working installation.
955	955	</para>
956
	956
957	957	<para>
958	958	PyKota features some interesting possibilities which allow you to
…	…
960	960	or on a per printer basis. Please see the sample configuration files
961	961	to see what I mean. In the simplest form, only a <literal>[global]</literal> section is
962		needed. In more complex configurations, you will have to create
	962	needed. In more complex configurations, you will have to create
963	963	one section per printer. Each section in the configuration files
964	964	begins with a name between square brackets <literal>[]</literal>.
…	…
966	966	of the print queue you want to manage with PyKota.
967	967	</para>
968
	968
969	969	<para>
970	970	After you have modified <application>PyKota</application>'s configuration files, you have to
…	…
980	980	file contains the read-write user's identity and password. You must then
981	981	ensure that no normal user can read this file. It should only be readable
982		by the <literal>root</literal> user, which is always the case, and by
	982	by the <literal>root</literal> user, which is always the case, and by
983	983	<application>PyKota</application> administrators. In addition,
984		users for which <application>CUPS</application> doesn't run as user <literal>root</literal> will
	984	users for which <application>CUPS</application> doesn't run as user <literal>root</literal> will
985	985	have to ensure that the user their printing system is run as
986	986	can read both of these files. An easy way to do so is to put the <literal>lp</literal> user
…	…
988	988	to give the correct permissions to <application>PyKota</application>'s configuration files :
989	989	<screen>
990		$ chown -R pykota.pykota ~pykota/
	990	$ chown -R pykota.pykota ~pykota/
991	991	$ chmod 750 ~pykota/
992		$ chmod 644 ~pykota/pykota.conf
993		$ chmod 640 ~pykota/pykotadmin.conf
	992	$ chmod 644 ~pykota/pykota.conf
	993	$ chmod 640 ~pykota/pykotadmin.conf
994	994	</screen>
995
	995
996	996	<warning>
997	997	<title>Warning</title>
998	998	<para>
999		All the users allowed to read the <filename>~pykota/pykotadmin.conf</filename>
	999	All the users allowed to read the <filename>~pykota/pykotadmin.conf</filename>
1000	1000	are considered to be <application>PyKota</application> administrators. So be
1001	1001	careful with these files permissions.
…	…
1003	1003	</warning>
1004	1004	</para>
1005
	1005
1006	1006	<para>
1007	1007	On some systems, you may be able to strenghten permissions like this :
1008	1008	<screen>
1009		$ chown -R pykota.pykota ~pykota/
	1009	$ chown -R pykota.pykota ~pykota/
1010	1010	$ chmod 750 ~pykota/
1011		$ chmod 640 ~pykota/pykota.conf
1012		$ chmod 600 ~pykota/pykotadmin.conf
	1011	$ chmod 640 ~pykota/pykota.conf
	1012	$ chmod 600 ~pykota/pykotadmin.conf
1013	1013	</screen>
1014	1014	</para>
1015
	1015
1016	1016	<para>
1017	1017	And on other ones, you may need to relax them, and change the files' owner :
1018	1018	<screen>
1019		$ chown pykota.pykota ~pykota/
	1019	$ chown pykota.pykota ~pykota/
1020	1020	$ chmod 755 ~pykota/
1021		$ chown lp.pykota ~pykota/pykota.conf
1022		$ chmod 640 ~pykota/pykota.conf
1023		$ chown lp.pykota ~pykota/pykotadmin.conf
1024		$ chmod 640 ~pykota/pykotadmin.conf
	1021	$ chown lp.pykota ~pykota/pykota.conf
	1022	$ chmod 640 ~pykota/pykota.conf
	1023	$ chown lp.pykota ~pykota/pykotadmin.conf
	1024	$ chmod 640 ~pykota/pykotadmin.conf
1025	1025	</screen>
1026	1026	</para>
1027
	1027
1028	1028	<para>
1029	1029	This all depends on the printing system you are using, and the user the
1030	1030	printing system is usually running as. You need to remember three things :
1031
	1031
1032	1032	<itemizedlist>
1033	1033	<listitem>
…	…
1035	1035	The user your printing system runs as MUST be allowed to read
1036	1036	both <application>PyKota</application>'s configuration files.
1037		</para>
1038		</listitem>
1039		<listitem>
	1037	</para>
	1038	</listitem>
	1039	<listitem>
1040	1040	<para>
1041	1041	Any user who can read <filename>pykotadmin.conf</filename>
…	…
1044	1044	</para>
1045	1045	</listitem>
1046		<listitem>
	1046	<listitem>
1047	1047	<para>
1048	1048	If <filename>cupsd.conf</filename> contains <literal>RunAsUser</literal>, then
…	…
1052	1052	</para>
1053	1053	</listitem>
1054		</itemizedlist>
1055		</para>
1056
	1054	</itemizedlist>
	1055	</para>
	1056
1057	1057	<para>
1058	1058	Don't forget to restart your print server sofware if you changed group membership for the user it runs
1059	1059	as, otherwise your change wouldn't be taken into account.
1060	1060	</para>
1061
	1061
1062	1062	<para>
1063	1063	Now depending on your printing system, the configuration to do is particular.
…	…
1065	1065	is not supported anymore.
1066	1066	</para>
1067
	1067
1068	1068	<sect3>
1069	1069	<title>With CUPS</title>
1070
	1070
1071	1071	<para>
1072	1072	From version 1.16alpha7 on, configuring <application>PyKota</application> to integrate
1073	1073	within <application>CUPS</application> is more than easy.
1074	1074	</para>
1075
	1075
1076	1076	<para>
1077	1077	You just have to create a symbolic link to the <command>cupspykota</command>
1078	1078	command in <application>CUPS</application>' backend directory :
1079		<screen>
1080		$ cd /usr/lib/cups/backend
	1079	<screen>
	1080	$ cd /usr/lib/cups/backend
1081	1081	$ ln -s /usr/share/pykota/cupspykota cupspykota
1082	1082	</screen>
1083	1083	</para>
1084
	1084
1085	1085	<para>
1086	1086	If you use CUPS v1.2 or higher, you must
…	…
1088	1088	backend to correctly support other backends which must be run
1089	1089	as the root user (e.g. the <command>lpd</command> backend) :
1090		<screen>
	1090	<screen>
1091	1091	$ chmod 700 /usr/share/pykota/cupspykota
1092	1092	</screen>
1093	1093	</para>
1094
	1094
1095	1095	<para>
1096	1096	You have to restart <application>CUPS</application> for this modification to
1097		take effect :
	1097	take effect :
1098	1098	<screen>
1099		$ /etc/init.d/cupsys restart
	1099	$ /etc/init.d/cupsys restart
1100	1100	</screen>
1101	1101	</para>
1102
1103		<para>
1104		Now point your web browser to CUPS configuration page, usually at
	1102
	1103	<para>
	1104	Now point your web browser to CUPS configuration page, usually at
1105	1105	<ulink url="http://localhost:631">http://localhost:631</ulink> on
1106	1106	your print server.
1107	1107	</para>
1108
	1108
1109	1109	<para>
1110	1110	Then when creating new printers or reconfiguring existing ones, just
…	…
1114	1114	Debian 3.0 Woody is known to have problems : CUPS 1.1.14 doesn't automatically
1115	1115	detect <literal>PyKota managed</literal> devices. So you have to manually
1116		modify CUPS' <filename>printers.conf</filename> file as explained in
	1116	modify CUPS' <filename>printers.conf</filename> file as explained in
1117	1117	PyKota's toplevel <filename>README</filename> file.
1118	1118	</para>
…	…
1123	1123	one.
1124	1124	</para>
1125
	1125
1126	1126	<para>
1127	1127	Repeat the above procedure for each print queue on which you want to use
1128	1128	PyKota. That's all !
1129	1129	</para>
1130
	1130
1131	1131	<sect4>
1132	1132	<title>Troubleshooting</title>
…	…
1136	1136	well as the hardware and software you use.
1137	1137	</para>
1138
	1138
1139	1139	<para>
1140		A searchable FAQ is now available at
	1140	A searchable FAQ is now available at
1141	1141	<ulink url="http://otrs.librelogiciel.com/otrs/public.pl">http://otrs.librelogiciel.com/public.pl</ulink>.
1142	1142	A FAQ entry explaining in great details how to diagnose a problem correctly is
1143		available at
	1143	available at
1144	1144	<ulink url="http://otrs.librelogiciel.com/otrs/public.pl?ID=2">http://otrs.librelogiciel.com/public.pl?ID=2</ulink>.
1145	1145	</para>
1146
	1146
1147	1147	<para>
1148	1148	You can also ask questions on IRC :
1149	1149	<screen>
1150		/server irc.freenode.net
	1150	/server irc.freenode.net
1151	1151	/join #pykota
1152	1152	</screen>
1153		</para>
1154		</sect4>
1155
	1153	</para>
	1154	</sect4>
	1155
1156	1156	</sect3>
1157
1158		</sect2>
	1157
	1158	</sect2>
1159	1159	</sect1>
1160	1160	</chapter>

pykota/trunk/docs/introduction.sgml

r3345	r3413
3	3	<chapter>
4	4	<title id="introduction">Introduction to PyKota</title>
5
	5
6	6	<para>Last modified on $Date$</para>
7
	7
8	8	<para>
9	9	This chapter will briefly introduce you to PyKota, and will familiarize
10	10	you with this software and its components.
11	11	</para>
12
13
	12
	13
14	14	<sect1>
15	15	<title>What is <application>PyKota</application> ?</title>
16
	16
17	17	<para>
18	18	<application>PyKota</application> is a print quota and print accounting software solution
19	19	for GNU/Linux and compatible print servers.
20	20	</para>
21
	21
22	22	<para>
23	23	PyKota currently supports the
24	24	<ulink url="http://www.cups.org"><application>CUPS</application></ulink>
25	25	<footnote><para>Common UNIX Printing System</para></footnote>
26		printing subsystem, although older releases also supported
	26	printing subsystem, although older releases also supported
27	27	<ulink url="http://lprng.sourceforge.net"><application>LPRng</application></ulink>.
28	28	</para>
29
	29
30	30	<para>
31	31	PyKota is distributed under the terms of the GNU General Public License of the
…	…
34	34	the terms of this license.
35	35	</para>
36
	36
37	37	<para>
38	38	We believe that despite being a bit rough around the edges sometimes, <application>PyKota</application>
…	…
41	41	for the next release.
42	42	</para>
43
	43
44	44	<para>
45	45	<application>PyKota</application> is however a somewhat complex piece of software, and installing
…	…
47	47	next chapter.
48	48	</para>
49
	49
50	50	<para>
51	51	<application>PyKota</application> is made of the following components :
…	…
73	73	so please give particular attention to this file's permissions.
74	74	</para>
75		</listitem>
76		<listitem>
77		<para>
78		<filename>pykota.conf</filename> : this is the main configuration file for
	75	</listitem>
	76	<listitem>
	77	<para>
	78	<filename>pykota.conf</filename> : this is the main configuration file for
79	79	<application>PyKota</application>. It contains database settings which
80	80	allow the <application>PyKota</application> software to access to the print
81	81	quota database in readonly mode, as well as global and print queue specific
82		configuration directives. With a properly configured <application>PyKota</application>,
	82	configuration directives. With a properly configured <application>PyKota</application>,
83	83	letting normal users read this file is safe
84	84	excepted where you want to forbid users to read other users' print quota
…	…
87	87	use any of the <application>PyKota</application> command line tools.
88	88	</para>
89		</listitem>
	89	</listitem>
90	90	</itemizedlist>
91	91	</para>
92		</listitem>
	92	</listitem>
93	93	<listitem>
94	94	<para>
…	…
100	100	for other database backends might be added in a future release.
101	101	</para>
102		</listitem>
	102	</listitem>
103	103	<listitem>
104	104	<para>
…	…
108	108	of circumstances like the user being over quota, and interact with the end user through the use of external
109	109	commands or shell scripts. This software is written in such a manner than system
110		administrators can plug their own scripts at the most strategic points of the
	110	administrators can plug their own scripts at the most strategic points of the
111	111	printing process, through specific directives that you put in <application>PyKota</application>'s
112	112	configuration files.
113	113	</para>
114		</listitem>
	114	</listitem>
115	115	<listitem>
116	116	<para>
…	…
126	126	interactive way, but currently only under Debian and Ubuntu.
127	127	</para>
128		</listitem>
	128	</listitem>
129	129	<listitem>
130	130	<para>
…	…
133	133	into a turn-key solution, hence the name.
134	134	</para>
135		</listitem>
	135	</listitem>
136	136	<listitem>
137	137	<para>
138	138	<command>pkprinters</command> : to manage printers and printers groups.
139	139	</para>
140		</listitem>
	140	</listitem>
141	141	<listitem>
142	142	<para>
143	143	<command>pkusers</command> : to manage users and users groups.
144	144	</para>
145		</listitem>
	145	</listitem>
146	146	<listitem>
147	147	<para>
148	148	<command>edpykota</command> : to manage users' and users groups' print quota entries.
149	149	</para>
150		</listitem>
	150	</listitem>
151	151	<listitem>
152	152	<para>
153	153	<command>pkbcodes</command> : to manage billing codes.
154	154	</para>
155		</listitem>
	155	</listitem>
156	156	<listitem>
157	157	<para>
158	158	<command>repykota</command> : to do some basic print quota reporting.
159	159	</para>
160		</listitem>
	160	</listitem>
161	161	<listitem>
162	162	<para>
…	…
166	166	numerous output formats are supported, like <acronym>csv</acronym> and <acronym>XML</acronym>
167	167	</para>
168		</listitem>
	168	</listitem>
169	169	<listitem>
170	170	<para>
…	…
173	173	instead from <filename>pykota.conf</filename>'s <literal>policy</literal> directive.
174	174	</para>
175		</listitem>
	175	</listitem>
176	176	<listitem>
177	177	<para>
…	…
180	180	application which works under the X Window system.
181	181	</para>
182		</listitem>
	182	</listitem>
183	183	<listitem>
184	184	<para>
…	…
187	187	a less costly printer.
188	188	</para>
189		</listitem>
	189	</listitem>
190	190	<listitem>
191	191	<para>
…	…
193	193	This command is
194	194	not meant to be used from the command line, but
195		instead from <filename>pykota.conf</filename>'s <literal>startingbanner</literal>
	195	instead from <filename>pykota.conf</filename>'s <literal>startingbanner</literal>
196	196	and <literal>endingbanner</literal> directives. If you prefer you can use
197	197	your own generator of dynamic banner pages or even static banner pages.
198	198	</para>
199		</listitem>
	199	</listitem>
200	200	<listitem>
201	201	<para>
…	…
204	204	this command is meant to be used as a periodic reminder.
205	205	</para>
206		</listitem>
	206	</listitem>
207	207	<listitem>
208	208	<para>
…	…
210	210	tools allow you to interact with end users at printing time.
211	211	</para>
212		</listitem>
	212	</listitem>
213	213	<listitem>
214	214	<para>
…	…
216	216	for your users from their printing history.
217	217	</para>
218		</listitem>
219		<listitem>
220		<para>
221		<command>pkrefund</command> : a tool with which you can refund print jobs
	218	</listitem>
	219	<listitem>
	220	<para>
	221	<command>pkrefund</command> : a tool with which you can refund print jobs
222	222	when there was an accounting problem. It can generate printable receipts
223	223	in the PDF format.
224	224	</para>
225		</listitem>
	225	</listitem>
226	226	</itemizedlist>
227	227	</para>
228		</listitem>
	228	</listitem>
229	229	<listitem>
230	230	<para>
…	…
236	236	<listitem>
237	237	<para>
238		<command>printquota.cgi</command> : to do basic print quota reports like repykota,
	238	<command>printquota.cgi</command> : to do basic print quota reports like repykota,
239	239	and also to examine the printing history, which is not possible with repykota for now.
240	240	</para>
241		</listitem>
	241	</listitem>
242	242	<listitem>
243	243	<para>
…	…
245	245	command line tool, but works from within a web browser.
246	246	</para>
247		</listitem>
	247	</listitem>
248	248	<listitem>
249	249	<para>
…	…
251	251	command line tool, but works from within a web browser.
252	252	</para>
253		</listitem>
	253	</listitem>
254	254	</itemizedlist>
255	255	</para>
256		</listitem>
	256	</listitem>
257	257	<listitem>
258	258	<para>
…	…
261	261	you may find interesting things...
262	262	</para>
263		</listitem>
	263	</listitem>
264	264	</itemizedlist>
265	265	</para>
266
267		</sect1>
268
	266
	267	</sect1>
	268
269	269	</chapter>
270	270

pykota/trunk/docs/pkbanner.sgml

r2561	r3413
4	4	<title>Generate banners with pkbanner</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	<application>CUPS</application> integrated bannering facility sucks because banners can only
…	…
10	10	to have several banners and jobs mixed in an unexpected way because of the way <application>CUPS</application>
11	11	works.
12		</para>
13
	12	</para>
	13
14	14	<para>
15	15	To fix this problem for good, <application>PyKota</application> can use its own banners, which can be :
…	…
22	22	<listitem>
23	23	<para>
24		The output of any executable command of your choice, launched at printing time,
	24	The output of any executable command of your choice, launched at printing time,
25	25	and to which are made available a bunch of environment variables which can help
26		your command create a purely dynamic banner on the fly. In particular your
	26	your command create a purely dynamic banner on the fly. In particular your
27	27	command knows all about the status of the current user's print quota information.
28	28	</para>
…	…
30	30	</itemizedlist>
31	31	</para>
32
	32
33	33	<para>
34	34	Although you can use any command to generate banners for you, you can also use
…	…
36	36	It was designed for ease of use, without any compromise on its flexibility.
37	37	</para>
38
	38
39	39	<para>
40	40	For example <command>pkbanner</command> allows you to specify a particular logo and url to be
41		printed on the banner pages, as well as define a transparency factor to save toner while
	41	printed on the banner pages, as well as define a transparency factor to save toner while
42	42	printing banners. You can also choose a particular page size to use, as well as include
43	43	additionnal textual information on the banner page.
44	44	</para>
45
	45
46	46	<para>
47	47	<command>pkbanner</command> generates PostScript code, but <application>PyKota</application>
…	…
49	49	another file format for your printer.
50	50	</para>
51
	51
52	52	<para>
53		<command>pkbanner</command> is not meant to be launched from the command line though,
	53	<command>pkbanner</command> is not meant to be launched from the command line though,
54	54	but only through the <literal>startingbanner</literal> and <literal>endingbanner</literal>
55	55	directives in <filename>pykota.conf</filename>.
56	56	</para>
57
	57
58	58	<sect1>
59	59	<title>Reference</title>
…	…
66	66	<arg>-l <replaceable>image</replaceable></arg>
67	67	<arg>--logo <replaceable>image</replaceable></arg>
68		</group>
	68	</group>
69	69	<group choice="opt">
70	70	<arg>-p <replaceable>size</replaceable></arg>
71	71	<arg>--pagesize <replaceable>size</replaceable></arg>
72		</group>
	72	</group>
73	73	<group choice="opt">
74	74	<arg>-s <replaceable>luminosity</replaceable></arg>
75	75	<arg>--savetoner <replaceable>luminosity</replaceable></arg>
76		</group>
	76	</group>
77	77	<group choice="opt">
78	78	<arg>-u <replaceable>link</replaceable></arg>
79	79	<arg>--url <replaceable>link</replaceable></arg>
80		</group>
	80	</group>
81	81	<group choice="opt">
82	82	<arg><replaceable>additionnal info</replaceable></arg>

pykota/trunk/docs/pkbcodes.sgml

r2555	r3413
4	4	<title>Manage billing codes with pkbcodes</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	Some people like lawyers for example need to be able to invoice their own clients
…	…
10	10	the possibility to attach a particular billing code to each print job, and of course,
11	11	<application>PyKota</application> can make use of it.
12		</para>
13
	12	</para>
	13
14	14	<para>
15		To use a billing code when printing, you have to pass an additionnal argument to the
	15	To use a billing code when printing, you have to pass an additionnal argument to the
16	16	<command>lp</command> command, for example for a client named <literal>smith</literal>
17	17	this could be something like :
…	…
20	20	</screen>
21	21	</para>
22
	22
23	23	<para>
24	24	For <application>PyKota</application> to be able to maintain statistics
…	…
26	26	database. This is the main goal of the <command>pkbcodes</command> command line tool.
27	27	</para>
28
	28
29	29	<para>
30	30	But <command>pkbcodes</command> also allows you to add a textual description to each billing
…	…
32	32	existing billing codes.
33	33	</para>
34
	34
35	35	<para>
36	36	With the help of the <literal>unknown_billingcode</literal> directive in
…	…
41	41	administrator.
42	42	</para>
43
	43
44	44	<para>
45	45	Finally, the <literal>overwrite_jobticket</literal> directive in
…	…
48	48	doesn't allow end users to give a value to the billing code when submitting the print job.
49	49	</para>
50
	50
51	51	<sect1>
52	52	<title>Reference</title>

pykota/trunk/docs/pkinvoice.sgml

r3115	r3413
4	4	<title>Invoice your users with pkinvoice</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	<command>pkinvoice</command> is a command line tool with which you'll be able to extract jobs from the printing history,
9	9	and generate nice looking and configurable <acronym>PDF</acronym> invoices.
10		</para>
11
	10	</para>
	11
12	12	<para>
13	13	You'll be allowed to optionally filter the data extraction based on starting and ending dates, which
14	14	defaults to the complete history, user, printer, client hostname, etc...
15	15	</para>
16
	16
17	17	<para>
18	18	The generated documents will contain one page per user, and the amount on the invoice will represent
19	19	how many credits each user spent during the specified time period.
20	20	</para>
21
	21
22	22	<para>
23	23	For more details, please refer to <command>pkinvoice</command>'s manual page.

pykota/trunk/docs/pknotify.sgml

r2836	r3413
4	4	<title>Interact with end users with pknotify and pykoticon</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	Printing under GNU/Linux and UNIX-Like systems usually lack features to dialog with end users.
…	…
10	10	silently.
11	11	</para>
12
	12
13	13	<para>
14	14	Some add-ons to printing systems, like print accounting software, could however benefit
…	…
17	17	do so in a completely generic way.
18	18	</para>
19
	19
20	20	<para>
21	21	<application>PyKotIcon</application> is a cross-platform, generic, networked, dialog box manager
…	…
49	49	</itemizedlist>
50	50	</para>
51
	51
52	52	<para>
53	53	It is important to know that <application>PyKotIcon</application> is completely independant from <application>PyKota</application>
…	…
55	55	knows NOTHING about print accounting, and doesn't need to. That's why it's distributed separately.
56	56	</para>
57
	57
58	58	<para>
59	59	<application>pknotify</application> is a client program for <application>PyKotIcon</application>, which is usually
…	…
61	61	from the command line as well, if needed.
62	62	</para>
63
	63
64	64	<para>
65	65	<application>pknotify</application>, through command line options, can use any of the functions published
…	…
72	72	allowed to continue until the next phase of print accounting and optional quota enforcement.
73	73	</para>
74
	74
75	75	<para>
76	76	For more details, see <command>pknotify</command>'s manual page.
77	77	</para>
78
	78
79	79	<warning><title>Warning</title>
80	80	<para>

pykota/trunk/docs/pkprinters.sgml

r2551	r3413
4	4	<title>Manage printers with pkprinters</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8		<command>pkprinters</command> is the preferred tool to manage printers in <application>PyKota</application>.
	8	<command>pkprinters</command> is the preferred tool to manage printers in <application>PyKota</application>.
9	9	It only manages printers, and do it well. With it you can add or delete printers or printer groups, or modify
10	10	existing printers or printers groups. This is also the tool to use to put printers into one or more printers groups.
11		</para>
12
	11	</para>
	12
13	13	<para>
14		The very first thing you have to do once <application>PyKota</application> is installed but before it can work,
	14	The very first thing you have to do once <application>PyKota</application> is installed but before it can work,
15	15	is to add into <application>PyKota</application>'s database an entry for each of the print queues on
16	16	which you want to have print quota or accounting.
…	…
19	19	like full management of printers.
20	20	</para>
21
	21
22	22	<para>
23	23	Let's say your printing system has several print queues defined : <literal>HP2100</literal>, <literal>TekTro</literal>,
24	24	and <literal>StylusColor1</literal> and <literal>StylusColor2</literal>. You want to charge 5 cents per page on each of this print queues.
25	25	You just have to type :
26		<screen>
	26	<screen>
27	27	$ pkprinters --add --charge 0.05 HP2100 TekTro StylusColor1 StylusColor2
28	28	</screen>
…	…
33	33	</warning>
34	34	</para>
35
	35
36	36	<para>
37		After some minutes, you think that you should charge more on the <literal>StylusColor1</literal>
38		and <literal>StylusColor2</literal> because they can do color.
	37	After some minutes, you think that you should charge more on the <literal>StylusColor1</literal>
	38	and <literal>StylusColor2</literal> because they can do color.
39	39	You also want to enter a description for these printers, because you have several
40	40	of them :
41		<screen>
	41	<screen>
42	42	$ pkprinters --charge 0.25 "StylusColor*"
43	43	$ pkprinters --description "Stylus Color 900 First floor" StylusColor1
…	…
45	45	</screen>
46	46	</para>
47
	47
48	48	<para>
49	49	You can now verify what you did :
50		<screen>
	50	<screen>
51	51	$ pkprinters --list
52	52	HP2100 [] (0.0 + #*0.05)
…	…
56	56	</screen>
57	57	</para>
58
	58
59	59	<para>
60	60	The command above has listed all print queues present in <application>PyKota</application>'s database,
61		along with their optional description and their base cost formula.
	61	along with their optional description and their base cost formula.
62	62	The cost formula includes the price per job, <literal>0.0</literal> in our examples,
63	63	and the price per page (<literal>#</literal> representing the number of pages).
64	64	</para>
65
	65
66	66	<para>
67	67	If you defined printers groups, then the total cost is computed as the recursive
…	…
71	71	cost of printing on a particular printer for a particular user.
72	72	</para>
73
	73
74	74	<sect1>
75	75	<title>Reference</title>
…	…
89	89	<arg>-c <replaceable>p</replaceable>,<replaceable>j</replaceable></arg>
90	90	<arg>--charge <replaceable>p</replaceable>,<replaceable>j</replaceable></arg>
91		</group>
	91	</group>
92	92	<group choice="opt">
93	93	<arg>-g <replaceable>pgroup1</replaceable>,<replaceable>pgroup2</replaceable>,<replaceable>...</replaceable></arg>
94	94	<arg>--groups <replaceable>pgroup1</replaceable>,<replaceable>pgroup2</replaceable>,<replaceable>...</replaceable></arg>
95		</group>
	95	</group>
96	96	<group choice="opt"><arg>-l</arg><arg>--list</arg></group>
97	97	<group choice="opt"><arg>-r</arg><arg>--remove</arg></group>
…	…
100	100	<arg>-m <replaceable>s</replaceable></arg>
101	101	<arg>--maxjobsize <replaceable>s</replaceable></arg>
102		</group>
	102	</group>
103	103	<group choice="opt"><arg>-p</arg><arg>--passthrough</arg></group>
104	104	<group choice="opt"><arg>-n</arg><arg>--nopassthrough</arg></group>

pykota/trunk/docs/pkrefund.sgml

r3115	r3413
4	4	<title>Refund your users with pkrefund</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	<command>pkrefund</command> is a command line tool with which you'll be able to extract jobs from the printing history,
9	9	and refund them with the possibility to generate nice looking and configurable <acronym>PDF</acronym> receipts.
10		</para>
11
	10	</para>
	11
12	12	<para>
13	13	You'll be allowed to optionally filter the data extraction based on starting and ending dates, which
14	14	defaults to the complete history, user, printer, client hostname, etc...
15	15	</para>
16
	16
17	17	<para>
18	18	The generated documents will contain one page per user, with the number of pages and credits
19	19	which were refunded.
20	20	</para>
21
	21
22	22	<para>
23	23	For more details, please refer to <command>pkrefund</command>'s manual page.

pykota/trunk/docs/pkturnkey.sgml

r2560	r3413
4	4	<title>Initialize your database with pkturnkey</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	The ultimate goal of the <command>pkturnkey</command> command line tool is
9	9	to transform <application>PyKota</application> into a turn-key solution.
10		</para>
11
	10	</para>
	11
12	12	<para>
13	13	For now its functionnalities are fairly limited, but it can :
…	…
17	17	Import existing print queues into <application>PyKota</application>'s database.
18	18	</para>
19		</listitem>
	19	</listitem>
20	20	<listitem>
21	21	<para>
22	22	Import existing users into <application>PyKota</application>'s database.
23	23	</para>
24		</listitem>
	24	</listitem>
25	25	<listitem>
26	26	<para>
27	27	Import existing users groups into <application>PyKota</application>'s database.
28	28	</para>
29		</listitem>
	29	</listitem>
30	30	<listitem>
31	31	<para>
32	32	Tell you which accounting method is the best for your printers.
33	33	</para>
34		</listitem>
	34	</listitem>
35	35	</itemizedlist>
36	36	</para>
37
	37
38	38	<para>
39	39	In the future, it is possible that this command will entirely generate configuration
40		files for you, and do a bunch of other things to ease the installation and
	40	files for you, and do a bunch of other things to ease the installation and
41	41	configuration of <application>PyKota</application>
42	42	</para>
43
	43
44	44	<para>
45	45	One very important thing to remember is that, by default, <command>pkturnkey</command>
…	…
50	50	it would launch.
51	51	</para>
52
	52
53	53	<para>
54	54	You can restrict the datas you want to import into the database by using the
…	…
56	56	arguments at the end of the command line.
57	57	</para>
58
	58
59	59	<para>
60	60	The following example will import all existing print queues, as well as all
…	…
62	62	gid is comprised between 5000 and 6000 :
63	63	<screen>
64		$ pkturnkey --force --uidmin 1000 --dousers --uidmax 50000 --dogroups --gidmin 5000 --gidmax 6000
	64	$ pkturnkey --force --uidmin 1000 --dousers --uidmax 50000 --dogroups --gidmin 5000 --gidmax 6000
65	65	</screen>
66	66	</para>
67
	67
68	68	<sect1>
69	69	<title>Reference</title>
…	…
79	79	<arg>-u <replaceable>uid</replaceable></arg>
80	80	<arg>--uidmin <replaceable>uid</replaceable></arg>
81		</group>
	81	</group>
82	82	<group choice="opt">
83	83	<arg>-U <replaceable>uid</replaceable></arg>
84	84	<arg>--uidmax <replaceable>uid</replaceable></arg>
85		</group>
	85	</group>
86	86	<group choice="opt">
87	87	<arg>-g <replaceable>gid</replaceable></arg>
88	88	<arg>--gidmin <replaceable>gid</replaceable></arg>
89		</group>
	89	</group>
90	90	<group choice="opt">
91	91	<arg>-G <replaceable>gid</replaceable></arg>
92	92	<arg>--gidmax <replaceable>gid</replaceable></arg>
93		</group>
	93	</group>
94	94	</cmdsynopsis>
95	95	</para>

pykota/trunk/docs/pkusers.sgml

r2833	r3413
4	4	<title id="pkusers">Manage Users and Groups with pkusers</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	You'll use this tool to create, manage or delete users or users groups from the database.
…	…
10	10	MUST add this user or group to the database using <command>pkusers</command>.
11	11	</para>
12
	12
13	13	<para>
14	14	The simplest way to add an user named <literal>jerome</literal> to the database is
15	15	to type :
16		<screen>
	16	<screen>
17	17	$ pkusers --add jerome
18	18	</screen>
19	19	</para>
20
	20
21	21	<para>
22	22	The commands above have created user <literal>jerome</literal> in the database. By default this
…	…
24	24	user on any printer. This has to be done through the <command>edpykota</command> command line tool.
25	25	</para>
26
	26
27	27	<para>
28	28	You can apply different sorts of limitations to an user or users group, by specifying a
…	…
31	31	<listitem>
32	32	<para>
33		<literal>--limitby quota</literal> : Page quotas are defined for each user on each printer.
	33	<literal>--limitby quota</literal> : Page quotas are defined for each user on each printer.
34	34	This means that an user can be
35	35	limited to print more than 20 pages on printer <literal>HP2100</literal> while still
…	…
37	37	This is the default.
38	38	</para>
39		</listitem>
	39	</listitem>
40	40	<listitem>
41	41	<para>
…	…
48	48	user, account balance quotas are shared between all printers for a particular user.
49	49	</para>
50		</listitem>
	50	</listitem>
51	51	<listitem>
52	52	<para>
…	…
54	54	accounting continues to be done.
55	55	</para>
56		</listitem>
	56	</listitem>
57	57	<listitem>
58	58	<para>
…	…
61	61	This value is not supported for users groups.
62	62	</para>
63		</listitem>
	63	</listitem>
64	64	<listitem>
65	65	<para>
…	…
67	67	This value is not supported for users groups.
68	68	</para>
69		</listitem>
70		</itemizedlist>
	69	</listitem>
	70	</itemizedlist>
71	71	</para>
72
	72
73	73	<para>
74	74	Here's an incomplete list of features :
75
	75
76	76	<itemizedlist>
77	77	<listitem>
…	…
117	117	</itemizedlist>
118	118	</para>
119
	119
120	120	<para>
121	121	For more details on the use of <command>pkusers</command>, please see this command's manual
122	122	page or help.
123	123	</para>
124
	124
125	125	</chapter>
126	126

pykota/trunk/docs/pykosd.sgml

r2551	r3413
4	4	<title>Uses On Screen Display to show personal print quota information with pykosd</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8		<command>pykosd</command> is a graphical <application>X Window</application> application which when launched
	8	<command>pykosd</command> is a graphical <application>X Window</application> application which when launched
9	9	will display print quota information for the current user.
10		</para>
11
	10	</para>
	11
12	12	<para>
13	13	Whenever you launch <command>pykosd</command>, it will display the current user's print quota
14	14	information in the top-left corner of the screen, above all existing windows, and with
15		a transparent background.
	15	a transparent background.
16	16	</para>
17
	17
18	18	<para>
19	19	By default, the information will remain displayed during <literal>3</literal> seconds, and
20		will be refreshed every <literal>180</literal> seconds. The program will loop forever
	20	will be refreshed every <literal>180</literal> seconds. The program will loop forever
21	21	until <keysym>Ctrl+C</keysym> is pressed, unless a specific number of iterations was
22	22	asked for.
23
	23
24	24	<tip>
25	25	<title>Tip</title>
…	…
29	29	</tip>
30	30	</para>
31
	31
32	32	<sect1>
33	33	<title>Reference</title>

pykota/trunk/docs/pykota.sgml

r3407	r3413
71	71
72	72	<para>
73		This documentation is licensed under the terms of the GNU
	73	This documentation is licensed under the terms of the GNU
74	74	General Public License as described below.
75	75	</para>
76
	76
77	77	<para>
78	78	This program is free software: you can redistribute it and/or modify
…	…
81	81	(at your option) any later version.
82	82	</para>
83
	83
84	84	<para>
85	85	This program is distributed in the hope that it will be useful,
…	…
88	88	GNU General Public License for more details.
89	89	</para>
90
	90
91	91	<para>
92	92	You should have received a copy of the GNU General Public License
93	93	along with this program. If not, see <http://www.gnu.org/licenses/>.
94	94	</para>
95
	95
96	96	<para>
97	97	A copy of the entire license is included in the section entitled "GNU
…	…
117	117
118	118	&INTRODUCTION;
119
	119
120	120	&INSTALLATION;
121
	121
122	122	&FILTERPYKOTA;
123
	123
124	124	&PKTURNKEY;
125
	125
126	126	&PKPRINTERS;
127
	127
128	128	&PKUSERS;
129	129
130	130	&EDPYKOTA;
131
	131
132	132	&REPYKOTA;
133
134		&PYKOTME;
135
	133
	134	&PYKOTME;
	135
136	136	&WARNPYKOTA;
137
	137
138	138	&DUMPYKOTA;
139
	139
140	140	&PKBCODES;
141
	141
142	142	&PYKOSD;
143
	143
144	144	&AUTOPYKOTA;
145
	145
146	146	&PKINVOICE;
147
	147
148	148	&PKREFUND;
149
	149
150	150	&PKBANNER;
151
	151
152	152	&PKNOTIFY;
153
	153
154	154	&SCRIPTS;
155
	155
156	156	&GNUGPL;
157	157

pykota/trunk/docs/pykotme.sgml

r2909	r3413
4	4	<title id="pykotme">Get print quotes before printing for real with <command>pykotme</command></title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	PyKota features a print quote generator, named <command>pykotme</command>.
…	…
12	12	knowingly.
13	13	</para>
14
	14
15	15	<para>
16	16	To get a print quote, you have to launch <command>pykotme</command>
17	17	from the command line, passing your print job's content in any format
18		recognized by PyKota
	18	recognized by PyKota
19	19	<footnote><para>PyKota now uses <ulink url="http://www.pykota.com/software/pkpgcounter">pkpgcounter</ulink>
20	20	which recognizes PostScript (both binary and DSC compliant),
…	…
23	23	or on its standard input (i.e. in a shell pipe or redirection).
24	24	</para>
25
	25
26	26	<para>
27	27	Without any command line argument, <command>pykotme</command>
28	28	automatically reads your job's data from its standard input.
29	29	</para>
30
	30
31	31	<para>
32	32	By default, <command>pykotme</command>
…	…
38	38	them with commas.
39	39	</para>
40
	40
41	41	<para>
42	42	<command>pykotme</command>'s functionnality is also available through the
…	…
44	44	However without authentication <command>pykotme.cgi</command> will only
45	45	return the print job's size and not its cost, because the cost depends on
46		the value of the user's overcharging factor and the printer being used.
47		That's why if you want to
48		obtain the same functionnality with the <acronym>CGI</acronym> script than
	46	the value of the user's overcharging factor and the printer being used.
	47	That's why if you want to
	48	obtain the same functionnality with the <acronym>CGI</acronym> script than
49	49	with the command line tool, you must configure your web server to force
50	50	users to authenticate whevenver they access to <command>pykotme.cgi</command>.
51		Then they will be able to choose one or more printers (all by default),
	51	Then they will be able to choose one or more printers (all by default),
52	52	and also to enter their username,
53	53	and the exact cost of the print job will be computed.
54	54	</para>
55
	55
56	56	<sect1>
57	57	<title>Examples</title>
…	…
59	59	Here are some examples of <command>pykotme</command> usage.
60	60	</para>
61
	61
62	62	<para>
63	63	The simplest form :
64		<screen>
	64	<screen>
65	65	port50-2:~$ pykotme pykota.ps
66	66	Your account balance : 16.25
67	67	Job size : 22 pages
68	68	Cost on printer apple : 1.35
69		port50-2:~$
70		</screen>
	69	port50-2:~$
	70	</screen>
71	71	</para>
72
	72
73	73	<para>
74	74	More complex, with printer name wildcard and within a pipe :
75		<screen>
	75	<screen>
76	76	port50-2:~$ a2ps -o - pykota/README \| pykotme --printer "a*"
77	77	[pykota/README (plain): 6 pages on 3 sheets]
…	…
80	80	Job size : 3 pages
81	81	Cost on printer apple : 0.40
82		port50-2:~$
	82	port50-2:~$
83	83	</screen>
84	84	</para>
85	85	</sect1>
86
	86
87	87	<sect1>
88	88	<title>Reference</title>
…	…
95	95	<arg>-P <replaceable>printername</replaceable></arg>
96	96	<arg>--printer <replaceable>printername</replaceable></arg>
97		</group>
	97	</group>
98	98	<group choice="opt">
99	99	<arg><replaceable>filename1</replaceable></arg>
…	…
101	101	<arg><replaceable>...</replaceable></arg>
102	102	<arg><replaceable>filenameN</replaceable></arg>
103		</group>
	103	</group>
104	104	</cmdsynopsis>
105	105	</para>

pykota/trunk/docs/README

r3275	r3413
21	21	This directory contains PyKota documentation in DocBook format.
22	22
23		Unless you've purchased an official PyKota package, you're on your
24		own to compile the DocBook source files to output formats like HTML
25		or PDF.
	23	Unless you've purchased an official PyKota package, you're on your
	24	own to compile the DocBook source files to output formats like HTML
	25	or PDF.
26	26
27	27	There are also some documents in OpenOffice.org format.

pykota/trunk/docs/repykota.sgml

r2844	r3413
4	4	<title id="repykota">Create print quota usage reports with repykota</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	To account for print usage is good, however there must be a way to easily
…	…
10	10	reports describing current usage for every user on every printer.
11	11	</para>
12
	12
13	13	<sect1>
14	14	<title>Command line based Print Quota reports</title>
15
	15
16	16	<para>
17	17	PyKota features a quota report generator, named <command>repykota</command>,
18	18	with which you can print the current state of the quota database.
19	19	</para>
20
	20
21	21	<para>
22	22	<command>repykota</command> behaves differently when it is launched by a
23	23	<application>PyKota</application> administrator, compared to when it is launched by a normal user.
24		</para>
25
	24	</para>
	25
26	26	<para>
27		In the first case, the print quota report will contain current account balance,
	27	In the first case, the print quota report will contain current account balance,
28	28	soft and hard limits, number of pages printed since last reset, total number
29	29	of pages printed, total paid, for possibly all users or all groups, depending
30	30	on command line options.
31	31	</para>
32
	32
33	33	<para>
34	34	In the second case, i.e. when <command>repykota</command> is launched by
35		a normal user, the user will only be allowed to see informations about himself or
	35	a normal user, the user will only be allowed to see informations about himself or
36	36	the groups he his a member of.
37	37	</para>
38
	38
39	39	<para>
40	40	Any user can limit the report to only one or more printers, by specifying the
41		<literal>-P</literal> or <literal>--printer</literal> command line option,
	41	<literal>-P</literal> or <literal>--printer</literal> command line option,
42	42	followed by one or more printer name or wildcard. If more than one printer name
43	43	or wildcard is used, they must be separated by commas.
44	44	</para>
45
	45
46	46	<para>
47	47	Launching <command>repykota</command> with no arguments will generate
48	48	a complete print quota report, depending on what you are allowed to see.
49	49	</para>
50
	50
51	51	<para>
52	52	Use the <literal>--help</literal> command line argument to learn what are
53	53	the different command line options available.
54	54	</para>
55
	55
56	56	<sect2>
57	57	<title>Reference</title>
…	…
66	66	<arg>-P <replaceable>printername</replaceable></arg>
67	67	<arg>--printer <replaceable>printername</replaceable></arg>
68		</group>
	68	</group>
69	69	<group choice="opt">
70	70	<arg><replaceable>name1</replaceable></arg>
…	…
72	72	<arg><replaceable>...</replaceable></arg>
73	73	<arg><replaceable>nameN</replaceable></arg>
74		</group>
	74	</group>
75	75	</cmdsynopsis>
76	76	</para>
77	77	</sect2>
78	78	</sect1>
79
	79
80	80	<sect1>
81	81	<title>Web based Print Quota reports</title>
82
	82
83	83	<para>
84	84	<application>PyKota</application> also features a CGI script to remotely access
…	…
88	88	correctly.
89	89	</para>
90
	90
91	91	<para>
92	92	You may also want to copy the <acronym>CSS</acronym> stylesheets which are present in the
…	…
95	95	a nicer web interface.
96	96	</para>
97
	97
98	98	<para>
99	99	You can find <command>printquota.cgi</command> in the <filename>pykota/cgi-bin</filename>
100	100	directory. Here's how to install it, provided that your web server's <filename>cgi-bin</filename>
101	101	directory is <filename>/usr/lib/cgi-bin</filename> :
102		<screen>
	102	<screen>
103	103	port50-2:/home/jerome/pykota$ cp cgi-bin/printquota.cgi /usr/lib/cgi-bin
104	104	port50-2:/home/jerome/pykota$ chmod 755 /usr/lib/cgi-bin/printquota.cgi
…	…
112	112	must ensure that this user <emphasis>is not</emphasis> allowed to read <filename>~pykota/pykotadmin.conf</filename>
113	113	</para>
114		</note>
	114	</note>
115	115	</para>
116
	116
117	117	<para>
118	118	If you install the CGI script as described above, any user will be allowed to view the complete print
…	…
125	125	then there's no restriction on what may appear on the print quota report.
126	126	</para>
127
	127
128	128	<para>
129	129	To automatically ask for an authentication dialog whenever the CGI script is accessed, you have to configure
130		your web server to do so. If your webserver is <ulink url="http://httpd.apache.org"><application>Apache</application></ulink>, then it's relatively easy. First you have to put
	130	your web server to do so. If your webserver is <ulink url="http://httpd.apache.org"><application>Apache</application></ulink>, then it's relatively easy. First you have to put
131	131	<command>printquota.cgi</command> in its own subdirectory below your web server's <filename>cgi-bin</filename>
132	132	directory, for example in <filename>cgi-bin/PyKota/</filename>. Then use the <command>htpasswd</command>
…	…
140	140	authentication mechanism.
141	141	</para>
142
	142
143	143	<para>
144	144	The detailed procedure to do all this is out of the scope of the present document, please refer to
145		<application>Apache</application>'s <ulink url="http://httpd.apache.org/docs-project/">documentation</ulink>
	145	<application>Apache</application>'s <ulink url="http://httpd.apache.org/docs-project/">documentation</ulink>
146	146	for all the gory details.
147	147	</para>

pykota/trunk/docs/scripts.sgml

r2551	r3413
4	4	<title>Useful Shell Scripts</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	<application>PyKota</application> comes with a number of shell scripts which
…	…
10	10	them to your own configuration. All are installed in the <filename>/usr/share/pykota</filename>
11	11	directory.
12		</para>
13
	12	</para>
	13
14	14	<sect1>
15	15	<title>waitprinter.sh</title>
16	16	<para>
17		This script which accepts a printer's hostname or <acronym>IP</acronym> address as its first parameter
	17	This script which accepts a printer's hostname or <acronym>IP</acronym> address as its first parameter
18	18	is used to wait for a printer which supports the <acronym>SNMP</acronym> protocol to be in <literal>idle</literal> state.
19	19	It exits as soon as the printer is <literal>idle</literal>, else loops forever.
20	20	</para>
21
	21
22	22	<para>
23	23	When defining an hardware <literal>accounter</literal> for a printer, it is important to wait for the printer being
…	…
26	26	value will be lower than expected with regard to the real job's size.
27	27	</para>
28
	28
29	29	<para>
30	30	<command>waitprinter.sh</command> can be used to be sure that <application>PyKota</application>
31		waits until no job is being printed, and no paper sheet is travelling inside the printer.
	31	waits until no job is being printed, and no paper sheet is travelling inside the printer.
32	32	</para>
33
	33
34	34	<tip>
35	35	<title>Tip</title>
…	…
37	37	See the sample configuration file <filename>conf/pykota.conf.sample</filename> for examples.
38	38	</para>
39		</tip>
	39	</tip>
40	40	</sect1>
41
	41
42	42	<sect1>
43	43	<title>papwaitprinter.sh</title>
44	44	<para>
45		This script which accepts a printer's AppleTalk name as its first parameter
	45	This script which accepts a printer's AppleTalk name as its first parameter
46	46	is used to wait for a printer which supports the <acronym>AppleTalk</acronym> protocol to be in <literal>idle</literal> state.
47	47	It exits as soon as the printer is <literal>idle</literal>, else loops forever.
48	48	</para>
49
	49
50	50	<para>
51	51	When defining an hardware <literal>accounter</literal> for a printer, it is important to wait for the printer being
…	…
54	54	value will be lower than expected with regard to the real job's size.
55	55	</para>
56
	56
57	57	<para>
58	58	<command>papwaitprinter.sh</command> can be used to be sure that <application>PyKota</application>
59		waits until no job is being printed, and no paper sheet is travelling inside the printer.
60		</para>
61
	59	waits until no job is being printed, and no paper sheet is travelling inside the printer.
	60	</para>
	61
62	62	<tip>
63	63	<title>Tip</title>
…	…
65	65	See the sample configuration file <filename>conf/pykota.conf.sample</filename> for examples.
66	66	</para>
67		</tip>
	67	</tip>
68	68	</sect1>
69
	69
70	70	<sect1>
71	71	<title>mailandpopup.sh</title>
…	…
75	75	whenever print quota is low or reached.
76	76	</para>
77
	77
78	78	<para>
79		For this script to work successfully, you may need to have a <application>Samba</application>
	79	For this script to work successfully, you may need to have a <application>Samba</application>
80	80	Primary Domain Controller. Some modifications may be needed in other configurations.
81	81	</para>
82
	82
83	83	<tip>
84	84	<title>Tip</title>
…	…
86	86	See the sample configuration file <filename>conf/pykota.conf.sample</filename> for examples.
87	87	</para>
88		</tip>
	88	</tip>
89	89	</sect1>
90
	90
91	91	<sect1>
92	92	<title>pagecount.pl</title>
…	…
97	97	It accepts the printer's hostname or <acronym>IP</acronym> address as its first parameter,
98	98	and the optional <acronym>TCP</acronym> port as its second parameter (it defaults to 9100).
99		</para>
100
	99	</para>
	100
101	101	<para>
102	102	Most of the time you'll use this script in combination with a script which waits for the printer
103	103	to be in <literal>idle</literal> state, in something like :
104		<screen>
	104	<screen>
105	105	accounter: hardware(somewaitscript.sh && pagecount.pl %(printer)s)
106	106	</screen>
107	107	</para>
108
	108
109	109	<tip>
110	110	<title>Tip</title>
…	…
112	112	See the sample configuration file <filename>conf/pykota.conf.sample</filename> for examples.
113	113	</para>
114		</tip>
	114	</tip>
115	115	</sect1>
116	116	</chapter>

pykota/trunk/docs/warnpykota.sgml

r2844	r3413
4	4	<title>Warn users above print quota with warnpykota</title>
5	5	<para>Last modified on $Date$</para>
6
	6
7	7	<para>
8	8	Whenever a user tries to print a document, if he is over his print quota,
…	…
13	13	to print again.
14	14	</para>
15
	15
16	16	<para>
17	17	However this may not be sufficient, and you may want to warn users who
…	…
19	19	regular intervals, like every day, for example from a <application>cron</application> job.
20	20	</para>
21
	21
22	22	<para>
23	23	This may be useful if the user has reached his print quota, and have received an email message telling him so,
…	…
25	25	paper for example.
26	26	</para>
27
	27
28	28	<para>
29		The <command>warnpykota</command> command was written with this in mind.
	29	The <command>warnpykota</command> command was written with this in mind.
30	30	If you put this command in your <filename>crontab</filename>, launching it for example
31	31	every day, then you'll be sure that all your users who are above their print quota
…	…
33	33	but at least they won't be able to say that they didn't receive them ;-)
34	34	</para>
35
	35
36	36	<para>
37	37	When an user who is not a <application>PyKota</application> administrator launches this command, only him can receive a warning
…	…
43	43	command.
44	44	</para>
45
	45
46	46	<para>
47		<application>PyKota</application> administrators can pass additionnal user or group names
	47	<application>PyKota</application> administrators can pass additionnal user or group names
48	48	(or wildcard filters) to only check the users or groups whose name matches.
49		</para>
50
	49	</para>
	50
51	51	<sect1>
52	52	<title>Reference</title>
…	…
61	61	<arg>-P <replaceable>printername</replaceable></arg>
62	62	<arg>--printer <replaceable>printername</replaceable></arg>
63		</group>
	63	</group>
64	64	<group choice="opt">
65	65	<arg><replaceable>name1</replaceable></arg>
…	…
67	67	<arg><replaceable>...</replaceable></arg>
68	68	<arg><replaceable>nameN</replaceable></arg>
69		</group>
	69	</group>
70	70	</cmdsynopsis>
71	71	</para>

Context Navigation

Legend:

pykota/trunk/docs/autopykota.sgml

pykota/trunk/docs/dumpykota.sgml

pykota/trunk/docs/edpykota.sgml

pykota/trunk/docs/filterpykota.sgml

pykota/trunk/docs/installation.sgml

pykota/trunk/docs/introduction.sgml

pykota/trunk/docs/pkbanner.sgml

pykota/trunk/docs/pkbcodes.sgml

pykota/trunk/docs/pkinvoice.sgml

pykota/trunk/docs/pknotify.sgml

pykota/trunk/docs/pkprinters.sgml

pykota/trunk/docs/pkrefund.sgml

pykota/trunk/docs/pkturnkey.sgml

pykota/trunk/docs/pkusers.sgml

pykota/trunk/docs/pykosd.sgml

pykota/trunk/docs/pykota.sgml

pykota/trunk/docs/pykotme.sgml

pykota/trunk/docs/README

pykota/trunk/docs/repykota.sgml

pykota/trunk/docs/scripts.sgml

pykota/trunk/docs/warnpykota.sgml

Download in other formats: