From: Kern Sibbald Date: Thu, 13 Dec 2007 12:33:10 +0000 (+0000) Subject: Add new French manual X-Git-Tag: Release-3.0.0~2154 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=e132706135db6e49d8c19ab54da8ff61da7c0c5c;p=bacula%2Fdocs Add new French manual --- diff --git a/docs/manuals/fr/catalog/Makefile b/docs/manuals/fr/catalog/Makefile new file mode 100644 index 00000000..7f8c78fa --- /dev/null +++ b/docs/manuals/fr/catalog/Makefile @@ -0,0 +1,135 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=catalog + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Catalog Database Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Catalo*.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/catalog/Makefile.in b/docs/manuals/fr/catalog/Makefile.in new file mode 100644 index 00000000..7f8c78fa --- /dev/null +++ b/docs/manuals/fr/catalog/Makefile.in @@ -0,0 +1,135 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=catalog + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Catalog Database Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Catalo*.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/catalog/catalog.css b/docs/manuals/fr/catalog/catalog.css new file mode 100644 index 00000000..d1824aff --- /dev/null +++ b/docs/manuals/fr/catalog/catalog.css @@ -0,0 +1,30 @@ +/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ +.MATH { font-family: "Century Schoolbook", serif; } +.MATH I { font-family: "Century Schoolbook", serif; font-style: italic } +.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold } + +/* implement both fixed-size and relative sizes */ +SMALL.XTINY { font-size : xx-small } +SMALL.TINY { font-size : x-small } +SMALL.SCRIPTSIZE { font-size : smaller } +SMALL.FOOTNOTESIZE { font-size : small } +SMALL.SMALL { } +BIG.LARGE { } +BIG.XLARGE { font-size : large } +BIG.XXLARGE { font-size : x-large } +BIG.HUGE { font-size : larger } +BIG.XHUGE { font-size : xx-large } + +/* heading styles */ +H1 { } +H2 { } +H3 { } +H4 { } +H5 { } + +/* mathematics styles */ +DIV.displaymath { } /* math displays */ +TD.eqno { } /* equation-number cells */ + + +/* document-specific styles come next */ diff --git a/docs/manuals/fr/catalog/catalog.tex b/docs/manuals/fr/catalog/catalog.tex new file mode 100644 index 00000000..4a6ad9f5 --- /dev/null +++ b/docs/manuals/fr/catalog/catalog.tex @@ -0,0 +1,81 @@ +%% +%% +%% The following characters must be preceded by a backslash +%% to be entered as printable characters: +%% +%% # $ % & ~ _ ^ \ { } +%% + +\documentclass[11pt,a4paper]{book} +\usepackage{html} +\usepackage{float} +\usepackage{graphicx} +\usepackage{bacula} +\usepackage{longtable} +\usepackage{makeidx} +\usepackage{index} +\usepackage{setspace} +\usepackage{hyperref} +\usepackage{url} + + +\makeindex +\newindex{general}{idx}{ind}{General Index} + +\sloppy + +\begin{document} +\sloppy + +\newfont{\bighead}{cmr17 at 36pt} +\parskip 10pt +\parindent 0pt + +\title{\includegraphics{./bacula-logo.eps} \\ \bigskip + \Huge{Bacula Catalog Database Guide} + \begin{center} + \large{It comes in the night and sucks + the essence from your computers. } + \end{center} +} + + +\author{Kern Sibbald} +\date{\vspace{1.0in}\today \\ + This manual documents Bacula version \input{version} \\ + \vspace{0.2in} + Copyright \copyright 1999-2007, Free Software Foundation Europe + e.V. \\ + \vspace{0.2in} + Permission is granted to copy, distribute and/or modify this document under the terms of the + GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU Free Documentation License". +} + +\maketitle + +\clearpage +\tableofcontents +\clearpage +\listoffigures +\clearpage +\listoftables +\clearpage + +\include{catmaintenance} +\include{mysql} +\include{postgresql} +\include{sqlite} +\include{internaldb} +\include{fdl} + + +% The following line tells link_resolver.pl to not include these files: +% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main + +% pull in the index +\clearpage +\printindex[general] + +\end{document} diff --git a/docs/manuals/fr/catalog/catmaintenance.tex b/docs/manuals/fr/catalog/catmaintenance.tex new file mode 100644 index 00000000..bbdf013b --- /dev/null +++ b/docs/manuals/fr/catalog/catmaintenance.tex @@ -0,0 +1,762 @@ +%% +%% + +\chapter{Catalog Maintenance} +\label{CatMaintenanceChapter} +\index[general]{Maintenance!Catalog } +\index[general]{Catalog Maintenance } + +Without proper setup and maintenance, your Catalog may continue to grow +indefinitely as you run Jobs and backup Files, and/or it may become +very inefficient and slow. How fast the size of your +Catalog grows depends on the number of Jobs you run and how many files they +backup. By deleting records within the database, you can make space available +for the new records that will be added during the next Job. By constantly +deleting old expired records (dates older than the Retention period), your +database size will remain constant. + +If you started with the default configuration files, they already contain +reasonable defaults for a small number of machines (less than 5), so if you +fall into that case, catalog maintenance will not be urgent if you have a few +hundred megabytes of disk space free. Whatever the case may be, some knowledge +of retention periods will be useful. +\label{Retention} + +\section{Setting Retention Periods} +\index[general]{Setting Retention Periods } +\index[general]{Periods!Setting Retention } + +{\bf Bacula} uses three Retention periods: the {\bf File Retention} period, +the {\bf Job Retention} period, and the {\bf Volume Retention} period. Of +these three, the File Retention period is by far the most important in +determining how large your database will become. + +The {\bf File Retention} and the {\bf Job Retention} are specified in each +Client resource as is shown below. The {\bf Volume Retention} period is +specified in the Pool resource, and the details are given in the next chapter +of this manual. + +\begin{description} + +\item [File Retention = \lt{}time-period-specification\gt{}] + \index[general]{File Retention } + The File Retention record defines the length of time that Bacula will keep +File records in the Catalog database. When this time period expires, and if +{\bf AutoPrune} is set to {\bf yes}, Bacula will prune (remove) File records +that are older than the specified File Retention period. The pruning will +occur at the end of a backup Job for the given Client. Note that the Client +database record contains a copy of the File and Job retention periods, but +Bacula uses the current values found in the Director's Client resource to do +the pruning. + +Since File records in the database account for probably 80 percent of the +size of the database, you should carefully determine exactly what File +Retention period you need. Once the File records have been removed from +the database, you will no longer be able to restore individual files +in a Job. However, with Bacula version 1.37 and later, as long as the +Job record still exists, you will be able to restore all files in the +job. + +Retention periods are specified in seconds, but as a convenience, there are +a number of modifiers that permit easy specification in terms of minutes, +hours, days, weeks, months, quarters, or years on the record. See the +\ilink{ Configuration chapter}{Time} of this manual for additional details +of modifier specification. + +The default File retention period is 60 days. + +\item [Job Retention = \lt{}time-period-specification\gt{}] + \index[general]{Job Retention } + The Job Retention record defines the length of time that {\bf Bacula} +will keep Job records in the Catalog database. When this time period +expires, and if {\bf AutoPrune} is set to {\bf yes} Bacula will prune +(remove) Job records that are older than the specified Job Retention +period. Note, if a Job record is selected for pruning, all associated File +and JobMedia records will also be pruned regardless of the File Retention +period set. As a consequence, you normally will set the File retention +period to be less than the Job retention period. + +As mentioned above, once the File records are removed from the database, +you will no longer be able to restore individual files from the Job. +However, as long as the Job record remains in the database, you will be +able to restore all the files backuped for the Job (on version 1.37 and +later). As a consequence, it is generally a good idea to retain the Job +records much longer than the File records. + +The retention period is specified in seconds, but as a convenience, there +are a number of modifiers that permit easy specification in terms of +minutes, hours, days, weeks, months, quarters, or years. See the \ilink{ +Configuration chapter}{Time} of this manual for additional details of +modifier specification. + +The default Job Retention period is 180 days. + +\item [AutoPrune = \lt{}yes/no\gt{}] + \index[general]{AutoPrune } + If AutoPrune is set to {\bf yes} (default), Bacula will automatically apply +the File retention period and the Job retention period for the Client at the +end of the Job. + +If you turn this off by setting it to {\bf no}, your Catalog will grow each +time you run a Job. +\end{description} + +\label{CompactingMySQL} +\section{Compacting Your MySQL Database} +\index[general]{Database!Compacting Your MySQL } +\index[general]{Compacting Your MySQL Database } + +Over time, as noted above, your database will tend to grow. I've noticed that +even though Bacula regularly prunes files, {\bf MySQL} does not effectively +use the space, and instead continues growing. To avoid this, from time to +time, you must compact your database. Normally, large commercial database such +as Oracle have commands that will compact a database to reclaim wasted file +space. MySQL has the {\bf OPTIMIZE TABLE} command that you can use, and SQLite +version 2.8.4 and greater has the {\bf VACUUM} command. We leave it to you to +explore the utility of the {\bf OPTIMIZE TABLE} command in MySQL. + +All database programs have some means of writing the database out in ASCII +format and then reloading it. Doing so will re-create the database from +scratch producing a compacted result, so below, we show you how you can do +this for MySQL, PostgreSQL and SQLite. + +For a {\bf MySQL} database, you could write the Bacula database as an ASCII +file (bacula.sql) then reload it by doing the following: + +\footnotesize +\begin{verbatim} +mysqldump -f --opt bacula > bacula.sql +mysql bacula < bacula.sql +rm -f bacula.sql +\end{verbatim} +\normalsize + +Depending on the size of your database, this will take more or less time and a +fair amount of disk space. For example, if I cd to the location of the MySQL +Bacula database (typically /opt/mysql/var or something similar) and enter: + +\footnotesize +\begin{verbatim} +du bacula +\end{verbatim} +\normalsize + +I get {\bf 620,644} which means there are that many blocks containing 1024 +bytes each or approximately 635 MB of data. After doing the {\bf mysqldump}, I +had a bacula.sql file that had {\bf 174,356} blocks, and after doing the {\bf +mysql} command to recreate the database, I ended up with a total of {\bf +210,464} blocks rather than the original {\bf 629,644}. In other words, the +compressed version of the database took approximately one third of the space +of the database that had been in use for about a year. + +As a consequence, I suggest you monitor the size of your database and from +time to time (once every six months or year), compress it. + +\label{DatabaseRepair} +\label{RepairingMySQL} +\section{Repairing Your MySQL Database} +\index[general]{Database!Repairing Your MySQL } +\index[general]{Repairing Your MySQL Database } + +If you find that you are getting errors writing to your MySQL database, or +Bacula hangs each time it tries to access the database, you should consider +running MySQL's database check and repair routines. The program you need to +run depends on the type of database indexing you are using. If you are using +the default, you will probably want to use {\bf myisamchk}. For more details +on how to do this, please consult the MySQL document at: +\elink{ +http://www.mysql.com/doc/en/Repair.html} +{http://www.mysql.com/doc/en/Repair.html}. + +If the errors you are getting are simply SQL warnings, then you might try +running dbcheck before (or possibly after) using the MySQL database repair +program. It can clean up many of the orphaned record problems, and certain +other inconsistencies in the Bacula database. + +A typical cause of MySQL database problems is if your partition fills. In +such a case, you will need to create additional space on the partition or +free up some space then repair the database probably using {\bf myisamchk}. +Recently my root partition filled and the MySQL database was corrupted. +Simply running {\bf myisamchk -r} did not fix the problem. However, +the following script did the trick for me: + +\footnotesize +\begin{verbatim} +#!/bin/sh +for i in *.MYD ; do + mv $i x${i} + t=`echo $i | cut -f 1 -d '.' -` + mysql bacula <bacula.db +select * from sqlite_master where type='index' and tbl_name='File'; +\end{verbatim} +\normalsize + +If the indexes are not present, especially the JobId index, you can +create them with the following commands: + +\footnotesize +\begin{verbatim} +mysql bacula +CREATE INDEX file_jobid_idx on File (JobId); +CREATE INDEX file_jfp_idx on File (Job, FilenameId, PathId); +\end{verbatim} +\normalsize + + + +\label{CompactingPostgres} +\section{Compacting Your PostgreSQL Database} +\index[general]{Database!Compacting Your PostgreSQL } +\index[general]{Compacting Your PostgreSQL Database } + +Over time, as noted above, your database will tend to grow. I've noticed that +even though Bacula regularly prunes files, PostgreSQL has a {\bf VACUUM} +command that will compact your database for you. Alternatively you may want to +use the {\bf vacuumdb} command, which can be run from a cron job. + +All database programs have some means of writing the database out in ASCII +format and then reloading it. Doing so will re-create the database from +scratch producing a compacted result, so below, we show you how you can do +this for PostgreSQL. + +For a {\bf PostgreSQL} database, you could write the Bacula database as an +ASCII file (bacula.sql) then reload it by doing the following: + +\footnotesize +\begin{verbatim} +pg_dump -c bacula > bacula.sql +cat bacula.sql | psql bacula +rm -f bacula.sql +\end{verbatim} +\normalsize + +Depending on the size of your database, this will take more or less time and a +fair amount of disk space. For example, you can {\bf cd} to the location of +the Bacula database (typically /usr/local/pgsql/data or possible +/var/lib/pgsql/data) and check the size. + +There are certain PostgreSQL users who do not recommend the above +procedure. They have the following to say: +PostgreSQL does not +need to be dumped/restored to keep the database efficient. A normal +process of vacuuming will prevent the database from every getting too +large. If you want to fine-tweak the database storage, commands such +as VACUUM FULL, REINDEX, and CLUSTER exist specifically to keep you +from having to do a dump/restore. + +Finally, you might want to look at the PostgreSQL documentation on +this subject at +\elink{http://www.postgresql.org/docs/8.1/interactive/maintenance.html} +{http://www.postgresql.org/docs/8.1/interactive/maintenance.html}. + +\section{Compacting Your SQLite Database} +\index[general]{Compacting Your SQLite Database } +\index[general]{Database!Compacting Your SQLite } + +First please read the previous section that explains why it is necessary to +compress a database. SQLite version 2.8.4 and greater have the {\bf Vacuum} +command for compacting the database. + +\footnotesize +\begin{verbatim} +cd {\bf working-directory} +echo 'vacuum;' | sqlite bacula.db +\end{verbatim} +\normalsize + +As an alternative, you can use the following commands, adapted to your system: + + +\footnotesize +\begin{verbatim} +cd {\bf working-directory} +echo '.dump' | sqlite bacula.db > bacula.sql +rm -f bacula.db +sqlite bacula.db < bacula.sql +rm -f bacula.sql +\end{verbatim} +\normalsize + +Where {\bf working-directory} is the directory that you specified in the +Director's configuration file. Note, in the case of SQLite, it is necessary to +completely delete (rm) the old database before creating a new compressed +version. + +\section{Migrating from SQLite to MySQL} +\index[general]{MySQL!Migrating from SQLite to } +\index[general]{Migrating from SQLite to MySQL } + +You may begin using Bacula with SQLite then later find that you want to switch +to MySQL for any of a number of reasons: SQLite tends to use more disk than +MySQL; when the database is corrupted it is often more catastrophic than +with MySQL or PostgreSQL. +Several users have succeeded in converting from SQLite to MySQL by +exporting the MySQL data and then processing it with Perl scripts +prior to putting it into MySQL. This is, however, not a simple +process. + +\label{BackingUpBacula} +\section{Backing Up Your Bacula Database} +\index[general]{Backing Up Your Bacula Database } +\index[general]{Database!Backing Up Your Bacula } + +If ever the machine on which your Bacula database crashes, and you need to +restore from backup tapes, one of your first priorities will probably be to +recover the database. Although Bacula will happily backup your catalog +database if it is specified in the FileSet, this is not a very good way to do +it, because the database will be saved while Bacula is modifying it. Thus the +database may be in an instable state. Worse yet, you will backup the database +before all the Bacula updates have been applied. + +To resolve these problems, you need to backup the database after all the backup +jobs have been run. In addition, you will want to make a copy while Bacula is +not modifying it. To do so, you can use two scripts provided in the release +{\bf make\_catalog\_backup} and {\bf delete\_catalog\_backup}. These files +will be automatically generated along with all the other Bacula scripts. The +first script will make an ASCII copy of your Bacula database into {\bf +bacula.sql} in the working directory you specified in your configuration, and +the second will delete the {\bf bacula.sql} file. + +The basic sequence of events to make this work correctly is as follows: + +\begin{itemize} +\item Run all your nightly backups +\item After running your nightly backups, run a Catalog backup Job +\item The Catalog backup job must be scheduled after your last nightly backup + +\item You use {\bf RunBeforeJob} to create the ASCII backup file and {\bf + RunAfterJob} to clean up +\end{itemize} + +Assuming that you start all your nightly backup jobs at 1:05 am (and that they +run one after another), you can do the catalog backup with the following +additional Director configuration statements: + +\footnotesize +\begin{verbatim} +# Backup the catalog database (after the nightly save) +Job { + Name = "BackupCatalog" + Type = Backup + Client=rufus-fd + FileSet="Catalog" + Schedule = "WeeklyCycleAfterBackup" + Storage = DLTDrive + Messages = Standard + Pool = Default + # WARNING!!! Passing the password via the command line is insecure. + # see comments in make_catalog_backup for details. + RunBeforeJob = "/home/kern/bacula/bin/make_catalog_backup" + RunAfterJob = "/home/kern/bacula/bin/delete_catalog_backup" + Write Bootstrap = "/home/kern/bacula/working/BackupCatalog.bsr" +} +# This schedule does the catalog. It starts after the WeeklyCycle +Schedule { + Name = "WeeklyCycleAfterBackup + Run = Level=Full sun-sat at 1:10 +} +# This is the backup of the catalog +FileSet { + Name = "Catalog" + Include { + Options { + signature=MD5 + } + File = \lt{}working_directory\gt{}/bacula.sql + } +} +\end{verbatim} +\normalsize + +Be sure to write a bootstrap file as in the above example. However, it is preferable +to write or copy the bootstrap file to another computer. It will allow +you to quickly recover the database backup should that be necessary. If +you do not have a bootstrap file, it is still possible to recover your +database backup, but it will be more work and take longer. + + +\label{BackingUpBaculaSecurityConsiderations} +\section{Security considerations} +\index[general]{Backing Up Your Bacula Database - Security Considerations } +\index[general]{Database!Backing Up Your Bacula Database - Security Considerations } + +We provide make\_catalog\_backup as an example of what can be used to backup +your Bacula database. We expect you to take security precautions relevant +to your situation. make\_catalog\_backup is designed to take a password on +the command line. This is fine on machines with only trusted users. It is +not acceptable on machines without trusted users. Most database systems +provide a alternative method, which does not place the password on the +command line. + +The make\_catalog\_backup script contains some warnings about how to use it. Please +read those tips. + +To help you get started, we know PostgreSQL has a password file, +\elink{ +.pgpass}{http://www.postgresql.org/docs/8.2/static/libpq-pgpass.html}, and +we know MySQL has +\elink{ .my.cnf}{http://dev.mysql.com/doc/refman/4.1/en/password-security.html}. + +Only you can decide what is appropriate for your situation. We have provided +you with a starting point. We hope it helps. + + +\label{BackingUPOtherDBs} +\section{Backing Up Third Party Databases} +\index[general]{Backing Up Third Party Databases } +\index[general]{Databases!Backing Up Third Party } + +If you are running a database in production mode on your machine, Bacula will +happily backup the files, but if the database is in use while Bacula is +reading it, you may back it up in an unstable state. + +The best solution is to shutdown your database before backing it up, or use +some tool specific to your database to make a valid live copy perhaps by +dumping the database in ASCII format. I am not a database expert, so I cannot +provide you advice on how to do this, but if you are unsure about how to +backup your database, you might try visiting the Backup Central site, which +has been renamed Storage Mountain (www.backupcentral.com). In particular, +their +\elink{ Free Backup and Recovery +Software}{http://www.backupcentral.com/toc-free-backup-software.html} page has +links to scripts that show you how to shutdown and backup most major +databases. +\label{Size} + +\section{Database Size} +\index[general]{Size!Database } +\index[general]{Database Size } + +As mentioned above, if you do not do automatic pruning, your Catalog will grow +each time you run a Job. Normally, you should decide how long you want File +records to be maintained in the Catalog and set the {\bf File Retention} +period to that time. Then you can either wait and see how big your Catalog +gets or make a calculation assuming approximately 154 bytes for each File +saved and knowing the number of Files that are saved during each backup and +the number of Clients you backup. + +For example, suppose you do a backup of two systems, each with 100,000 files. +Suppose further that you do a Full backup weekly and an Incremental every day, +and that the Incremental backup typically saves 4,000 files. The size of your +database after a month can roughly be calculated as: + +\footnotesize +\begin{verbatim} + Size = 154 * No. Systems * (100,000 * 4 + 10,000 * 26) +\end{verbatim} +\normalsize + +where we have assumed four weeks in a month and 26 incremental backups per month. +This would give the following: + +\footnotesize +\begin{verbatim} + Size = 154 * 2 * (100,000 * 4 + 10,000 * 26) +or + Size = 308 * (400,000 + 260,000) +or + Size = 203,280,000 bytes +\end{verbatim} +\normalsize + +So for the above two systems, we should expect to have a database size of +approximately 200 Megabytes. Of course, this will vary according to how many +files are actually backed up. + +Below are some statistics for a MySQL database containing Job records for five +Clients beginning September 2001 through May 2002 (8.5 months) and File +records for the last 80 days. (Older File records have been pruned). For these +systems, only the user files and system files that change are backed up. The +core part of the system is assumed to be easily reloaded from the Red Hat rpms. + + +In the list below, the files (corresponding to Bacula Tables) with the +extension .MYD contain the data records whereas files with the extension .MYI +contain indexes. + +You will note that the File records (containing the file attributes) make up +the large bulk of the number of records as well as the space used (459 Mega +Bytes including the indexes). As a consequence, the most important Retention +period will be the {\bf File Retention} period. A quick calculation shows that +for each File that is saved, the database grows by approximately 150 bytes. + +\footnotesize +\begin{verbatim} + Size in + Bytes Records File + ============ ========= =========== + 168 5 Client.MYD + 3,072 Client.MYI + 344,394,684 3,080,191 File.MYD + 115,280,896 File.MYI + 2,590,316 106,902 Filename.MYD + 3,026,944 Filename.MYI + 184 4 FileSet.MYD + 2,048 FileSet.MYI + 49,062 1,326 JobMedia.MYD + 30,720 JobMedia.MYI + 141,752 1,378 Job.MYD + 13,312 Job.MYI + 1,004 11 Media.MYD + 3,072 Media.MYI + 1,299,512 22,233 Path.MYD + 581,632 Path.MYI + 36 1 Pool.MYD + 3,072 Pool.MYI + 5 1 Version.MYD + 1,024 Version.MYI +\end{verbatim} +\normalsize + +This database has a total size of approximately 450 Megabytes. + +If we were using SQLite, the determination of the total database size would be +much easier since it is a single file, but we would have less insight to the +size of the individual tables as we have in this case. + +Note, SQLite databases may be as much as 50\% larger than MySQL databases due +to the fact that all data is stored as ASCII strings. That is even binary +integers are stored as ASCII strings, and this seems to increase the space +needed. diff --git a/docs/manuals/fr/catalog/check_tex.pl b/docs/manuals/fr/catalog/check_tex.pl new file mode 100755 index 00000000..e12d51be --- /dev/null +++ b/docs/manuals/fr/catalog/check_tex.pl @@ -0,0 +1,152 @@ +#!/usr/bin/perl -w +# Finds potential problems in tex files, and issues warnings to the console +# about what it finds. Takes a list of files as its only arguments, +# and does checks on all the files listed. The assumption is that these are +# valid (or close to valid) LaTeX files. It follows \include statements +# recursively to pick up any included tex files. +# +# +# +# Currently the following checks are made: +# +# -- Multiple hyphens not inside a verbatim environment (or \verb). These +# should be placed inside a \verb{} contruct so they will not be converted +# to single hyphen by latex and latex2html. + + +# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com +# +# + +use strict; + +# The following builds the test string to identify and change multiple +# hyphens in the tex files. Several constructs are identified but only +# multiple hyphens are changed; the others are fed to the output +# unchanged. +my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{ +my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{ +my $c = '\\s*\\}'; # closing curly brace + +# This captures entire verbatim environments. These are passed to the output +# file unchanged. +my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c; + +# This captures \verb{..{ constructs. They are passed to the output unchanged. +my $verb = '\\\\verb\\*?(.).*?\\1'; + +# This captures multiple hyphens with a leading and trailing space. These are not changed. +my $hyphsp = '\\s\\-{2,}\\s'; + +# This identifies other multiple hyphens. +my $hyphens = '\\-{2,}'; + +# This identifies \hyperpage{..} commands, which should be ignored. +my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}'; + +# This builds the actual test string from the above strings. +#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens"; +my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens"; + + +sub get_includes { + # Get a list of include files from the top-level tex file. The first + # argument is a pointer to the list of files found. The rest of the + # arguments is a list of filenames to check for includes. + my $files = shift; + my ($fileline,$includefile,$includes); + + while (my $filename = shift) { + # Get a list of all the html files in the directory. + open my $if,"<$filename" or die "Cannot open input file $filename\n"; + $fileline = 0; + $includes = 0; + while (<$if>) { + chomp; + $fileline++; + # If a file is found in an include, process it. + if (($includefile) = /\\include\s*\{(.*?)\}/) { + $includes++; + # Append .tex to the filename + $includefile .= '.tex'; + + # If the include file has already been processed, issue a warning + # and don't do it again. + my $found = 0; + foreach (@$files) { + if ($_ eq $includefile) { + $found = 1; + last; + } + } + if ($found) { + print "$includefile found at line $fileline in $filename was previously included\n"; + } else { + # The file has not been previously found. Save it and + # recursively process it. + push (@$files,$includefile); + get_includes($files,$includefile); + } + } + } + close IF; + } +} + + +sub check_hyphens { + my (@files) = @_; + my ($filedata,$this,$linecnt,$before); + + # Build the test string to check for the various environments. + # We only do the conversion if the multiple hyphens are outside of a + # verbatim environment (either \begin{verbatim}...\end{verbatim} or + # \verb{--}). Capture those environments and pass them to the output + # unchanged. + + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # Set up to process the file data. + $linecnt = 1; + + # Go through the file data from beginning to end. For each match, save what + # came before it and what matched. $filedata now becomes only what came + # after the match. + # Chech the match to see if it starts with a multiple-hyphen. If so + # warn the user. Keep track of line numbers so they can be output + # with the warning message. + while ($filedata =~ /$teststr/os) { + $this = $&; + $before = $`; + $filedata = $'; + $linecnt += $before =~ tr/\n/\n/; + + # Check if the multiple hyphen is present outside of one of the + # acceptable constructs. + if ($this =~ /^\-+/) { + print "Possible unwanted multiple hyphen found in line ", + "$linecnt of file $file\n"; + } + $linecnt += $this =~ tr/\n/\n/; + } + } +} +################################################################## +# MAIN #### +################################################################## + +my (@includes,$cnt); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +get_includes(\@includes,@ARGV); + +check_hyphens(@includes); diff --git a/docs/manuals/fr/catalog/do_echo b/docs/manuals/fr/catalog/do_echo new file mode 100644 index 00000000..04b9f79a --- /dev/null +++ b/docs/manuals/fr/catalog/do_echo @@ -0,0 +1,6 @@ +# +# Avoid that @VERSION@ and @DATE@ are changed by configure +# This file is sourced by update_version +# +echo "s%@VERSION@%${VERSION}%g" >${out} +echo "s%@DATE@%${DATE}%g" >>${out} diff --git a/docs/manuals/fr/catalog/fdl.tex b/docs/manuals/fr/catalog/fdl.tex new file mode 100644 index 00000000..b46cd990 --- /dev/null +++ b/docs/manuals/fr/catalog/fdl.tex @@ -0,0 +1,485 @@ +% TODO: maybe get rid of centering + +\chapter{GNU Free Documentation License} +\index[general]{GNU Free Documentation License} +\index[general]{License!GNU Free Documentation} + +\label{label_fdl} + + \begin{center} + + Version 1.2, November 2002 + + + Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc. + + \bigskip + + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + \bigskip + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +\end{center} + + +\begin{center} +{\bf\large Preamble} +\end{center} + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +\begin{center} +{\Large\bf 1. APPLICABILITY AND DEFINITIONS} +\end{center} + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The \textbf{"Document"}, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as \textbf{"you"}. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A \textbf{"Modified Version"} of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A \textbf{"Secondary Section"} is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The \textbf{"Cover Texts"} are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A \textbf{"Transparent"} copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called \textbf{"Opaque"}. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The \textbf{"Title Page"} means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as \textbf{"Acknowledgements"}, +\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.) +To \textbf{"Preserve the Title"} +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +\begin{center} +{\Large\bf 2. VERBATIM COPYING} +\end{center} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\begin{center} +{\Large\bf 3. COPYING IN QUANTITY} +\end{center} + + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\begin{center} +{\Large\bf 4. MODIFICATIONS} +\end{center} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} +\item[A.] + Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. + +\item[B.] + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + +\item[C.] + State on the Title page the name of the publisher of the + Modified Version, as the publisher. + +\item[D.] + Preserve all the copyright notices of the Document. + +\item[E.] + Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + +\item[F.] + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + +\item[G.] + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. + +\item[H.] + Include an unaltered copy of this License. + +\item[I.] + Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + +\item[J.] + Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + +\item[K.] + For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + +\item[L.] + Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. + +\item[M.] + Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + +\item[N.] + Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. + +\item[O.] + Preserve any Warranty Disclaimers. +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\begin{center} +{\Large\bf 5. COMBINING DOCUMENTS} +\end{center} + + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + +\begin{center} +{\Large\bf 6. COLLECTIONS OF DOCUMENTS} +\end{center} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +\begin{center} +{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS} +\end{center} + + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +\begin{center} +{\Large\bf 8. TRANSLATION} +\end{center} + + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +\begin{center} +{\Large\bf 9. TERMINATION} +\end{center} + + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\begin{center} +{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE} +\end{center} + + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +\begin{center} +{\Large\bf ADDENDUM: How to use this License for your documents} +% TODO: this is too long for table of contents +\end{center} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\bigskip +\begin{quote} + Copyright \copyright YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +\end{quote} +\bigskip + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + +\bigskip +\begin{quote} + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. +\end{quote} +\bigskip + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +%--------------------------------------------------------------------- diff --git a/docs/manuals/fr/catalog/fix_tex.pl b/docs/manuals/fr/catalog/fix_tex.pl new file mode 100755 index 00000000..98657576 --- /dev/null +++ b/docs/manuals/fr/catalog/fix_tex.pl @@ -0,0 +1,184 @@ +#!/usr/bin/perl -w +# Fixes various things within tex files. + +use strict; + +my %args; + + +sub get_includes { + # Get a list of include files from the top-level tex file. + my (@list,$file); + + foreach my $filename (@_) { + $filename or next; + # Start with the top-level latex file so it gets checked too. + push (@list,$filename); + + # Get a list of all the html files in the directory. + open IF,"<$filename" or die "Cannot open input file $filename"; + while () { + chomp; + push @list,"$1.tex" if (/\\include\{(.*?)\}/); + } + + close IF; + } + return @list; +} + +sub convert_files { + my (@files) = @_; + my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt); + + $cnt = 0; + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # We look for a line that starts with \item, and indent the two next lines (if not blank) + # by three spaces. + my $linecnt = 3; + $indentcnt = 0; + $output = ""; + # Process a line at a time. + foreach (split(/\n/,$filedata)) { + $_ .= "\n"; # Put back the return. + # If this line is less than the third line past the \item command, + # and the line isn't blank and doesn't start with whitespace + # add three spaces to the start of the line. Keep track of the number + # of lines changed. + if ($linecnt < 3 and !/^\\item/) { + if (/^[^\n\s]/) { + $output .= " " . $_; + $indentcnt++; + } else { + $output .= $_; + } + $linecnt++; + } else { + $linecnt = 3; + $output .= $_; + } + /^\\item / and $linecnt = 1; + } + + + # This is an item line. We need to process it too. If inside a \begin{description} environment, convert + # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'. + $itemcnt = 0; + $filedata = $output; + $output = ""; + my ($before,$descrip,$this,$between); + + # Find any \begin{description} environment + while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) { + $output .= $` . $1; + $filedata = $3 . $'; + $descrip = $2; + + # Search for \item {\bf xxx} + while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) { + $descrip = $'; + $output .= $`; + ($between,$descrip) = find_matching_brace($descrip); + if (!$descrip) { + $linecnt = $output =~ tr/\n/\n/; + print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip); + } + + # Now do the replacement. + $between = '{' . $between . '}' if ($between =~ /\[|\]/); + $output .= "\\item \[$between\]"; + $itemcnt++; + } + $output .= $descrip; + } + $output .= $filedata; + + # If any hyphens or \item commnads were converted, save the file. + if ($indentcnt or $itemcnt) { + open OF,">$file" or die "Cannot open output file $file"; + print OF $output; + close OF; + print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n"; + print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n"; + } + + $cnt += $indentcnt + $itemcnt; + } + return $cnt; +} + +sub find_matching_brace { + # Finds text up to the next matching brace. Assumes that the input text doesn't contain + # the opening brace, but we want to find text up to a matching closing one. + # Returns the text between the matching braces, followed by the rest of the text following + # (which does not include the matching brace). + # + my $str = shift; + my ($this,$temp); + my $cnt = 1; + + while ($cnt) { + # Ignore verbatim constructs involving curly braces, or if the character preceding + # the curly brace is a backslash. + if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) { + $this .= $`; + $str = $'; + $temp = $&; + + if ((substr($this,-1,1) eq '\\') or + $temp =~ /^\\verb/) { + $this .= $temp; + next; + } + + $cnt += ($temp eq '{') ? 1 : -1; + # If this isn't the matching curly brace ($cnt > 0), include the brace. + $this .= $temp if ($cnt); + } else { + # No matching curly brace found. + return ($this . $str,''); + } + } + return ($this,$str); +} + +sub check_arguments { + # Checks command-line arguments for ones starting with -- puts them into + # a hash called %args and removes them from @ARGV. + my $args = shift; + my $i; + + for ($i = 0; $i < $#ARGV; $i++) { + $ARGV[$i] =~ /^\-+/ or next; + $ARGV[$i] =~ s/^\-+//; + $args{$ARGV[$i]} = ""; + delete ($ARGV[$i]); + + } +} + +################################################################## +# MAIN #### +################################################################## + +my @includes; +my $cnt; + +check_arguments(\%args); +die "No Files given to Check\n" if ($#ARGV < 0); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +@includes = get_includes(@ARGV); + +$cnt = convert_files(@includes); +print "No lines changed\n" unless $cnt; diff --git a/docs/manuals/fr/catalog/index.perl b/docs/manuals/fr/catalog/index.perl new file mode 100644 index 00000000..bc4e1b60 --- /dev/null +++ b/docs/manuals/fr/catalog/index.perl @@ -0,0 +1,564 @@ +# This module does multiple indices, supporting the style of the LaTex 'index' +# package. + +# Version Information: +# 16-Feb-2005 -- Original Creation. Karl E. Cunningham +# 14-Mar-2005 -- Clarified and Consolodated some of the code. +# Changed to smoothly handle single and multiple indices. + +# Two LaTeX index formats are supported... +# --- SINGLE INDEX --- +# \usepackage{makeidx} +# \makeindex +# \index{entry1} +# \index{entry2} +# \index{entry3} +# ... +# \printindex +# +# --- MULTIPLE INDICES --- +# +# \usepackage{makeidx} +# \usepackage{index} +# \makeindex -- latex2html doesn't care but LaTeX does. +# \newindex{ref1}{ext1}{ext2}{title1} +# \newindex{ref2}{ext1}{ext2}{title2} +# \newindex{ref3}{ext1}{ext2}{title3} +# \index[ref1]{entry1} +# \index[ref1]{entry2} +# \index[ref3]{entry3} +# \index[ref2]{entry4} +# \index{entry5} +# \index[ref3]{entry6} +# ... +# \printindex[ref1] +# \printindex[ref2] +# \printindex[ref3] +# \printindex +# ___________________ +# +# For the multiple-index style, each index is identified by the ref argument to \newindex, \index, +# and \printindex. A default index is allowed, which is indicated by omitting the optional +# argument. The default index does not require a \newindex command. As \index commands +# are encountered, their entries are stored according +# to the ref argument. When the \printindex command is encountered, the stored index +# entries for that argument are retrieved and printed. The title for each index is taken +# from the last argument in the \newindex command. +# While processing \index and \printindex commands, if no argument is given the index entries +# are built into a default index. The title of the default index is simply "Index". +# This makes the difference between single- and multiple-index processing trivial. +# +# Another method can be used by omitting the \printindex command and just using \include to +# pull in index files created by the makeindex program. These files will start with +# \begin{theindex}. This command is used to determine where to print the index. Using this +# approach, the indices will be output in the same order as the newindex commands were +# originally found (see below). Using a combination of \printindex and \include{indexfile} has not +# been tested and may produce undesireable results. +# +# The index data are stored in a hash for later sorting and output. As \printindex +# commands are handled, the order in which they were found in the tex filea is saved, +# associated with the ref argument to \printindex. +# +# We use the original %index hash to store the index data into. We append a \002 followed by the +# name of the index to isolate the entries in different indices from each other. This is necessary +# so that different indices can have entries with the same name. For the default index, the \002 is +# appended without the name. +# +# Since the index order in the output cannot be determined if the \include{indexfile} +# command is used, the order will be assumed from the order in which the \newindex +# commands were originally seen in the TeX files. This order is saved as well as the +# order determined from any printindex{ref} commands. If \printindex commnads are used +# to specify the index output, that order will be used. If the \include{idxfile} command +# is used, the order of the original newindex commands will be used. In this case the +# default index will be printed last since it doesn't have a corresponding \newindex +# command and its order cannot be determined. Mixing \printindex and \include{idxfile} +# commands in the same file is likely to produce less than satisfactory results. +# +# +# The hash containing index data is named %indices. It contains the following data: +#{ +# 'title' => { +# $ref1 => $indextitle , +# $ref2 => $indextitle , +# ... +# }, +# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +#} + + +# Globals to handle multiple indices. +my %indices; + +# This tells the system to use up to 7 words in index entries. +$WORDS_IN_INDEX = 10; + +# KEC 2-18-05 +# Handles the \newindex command. This is called if the \newindex command is +# encountered in the LaTex source. Gets the index ref and title from the arguments. +# Saves the index ref and title. +# Note that we are called once to handle multiple \newindex commands that are +# newline-separated. +sub do_cmd_newindex { + my $data = shift; + # The data is sent to us as fields delimited by their ID #'s. We extract the + # fields. + foreach my $line (split("\n",$data)) { + my @fields = split (/(?:\<\#\d+?\#\>)+/,$line); + + # The index name and title are the second and fourth fields in the data. + if ($line =~ /^ \001 + # @ -> \002 + # | -> \003 + $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines + # protect \001 occurring with images + $str =~ s/\001/\016/g; # 0x1 to 0xF + $str =~ s/\\\\/\011/g; # Double backslash -> 0xB + $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC + $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD + $str =~ s/!/\001/g; # Exclamation point -> 0x1 + $str =~ s/\013/!/g; # 0xD -> Exclaimation point + $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF + $str =~ s/@/\002/g; # At sign -> 0x2 + $str =~ s/\015/@/g; # 0xF to At sign + $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11 + $str =~ s/\|/\003/g; # Vertical line to 0x3 + $str =~ s/\017/|/g; # 0x11 to vertical line + $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is + $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot; + $str =~ s/\011/\\\\/g; # 0x11 to double backslash + local($key_part, $pageref) = split("\003", $str, 2); + + # For any keys of the form: blablabla!blablabla, which want to be split at the + # exclamation point, replace the ! with a comma and a space. We don't do it + # that way for this index. + $key_part =~ s/\001/, /g; + local(@keys) = split("\001", $key_part); + # If TITLE is not yet available use $before. + $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title))); + $TITLE = $before unless $TITLE; + # Save the reference + local($words) = ''; + if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; } + elsif ($SHORT_INDEX) { $words = &make_shortidxname; } + else { $words = &make_idxname; } + local($super_key) = ''; + local($sort_key, $printable_key, $cur_key); + foreach $key (@keys) { + $key =~ s/\016/\001/g; # revert protected \001s + ($sort_key, $printable_key) = split("\002", $key); + # + # RRM: 16 May 1996 + # any \label in the printable-key will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($printable_key =~ /tex2html_anchor_mark/ ) { + $printable_key =~ s/><\/A>$cross_ref_mark/ + $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_label = $external_labels{$label} unless + ($ref_label = $ref_files{$label}); + '"' . "$ref_label#$label" . '">' . + &get_ref_mark($label,$id)} + /geo; + } + $printable_key =~ s/<\#[^\#>]*\#>//go; + #RRM + # recognise \char combinations, for a \backslash + # + $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s + $printable_key =~ s/\&\#;\`
/\\/g; # ditto + $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto + # + # $sort_key .= "@$printable_key" if !($printable_key); # RRM + $sort_key .= "@$printable_key" if !($sort_key); # RRM + $sort_key =~ tr/A-Z/a-z/; + if ($super_key) { + $cur_key = $super_key . "\001" . $sort_key; + $sub_index{$super_key} .= $cur_key . "\004"; + } else { + $cur_key = $sort_key; + } + + # Append the $index_name to the current key with a \002 delimiter. This will + # allow the same index entry to appear in more than one index. + $index_key = $cur_key . "\002$index_name"; + + $index{$index_key} .= ""; + + # + # RRM, 15 June 1996 + # if there is no printable key, but one is known from + # a previous index-entry, then use it. + # + if (!($printable_key) && ($printable_key{$index_key})) + { $printable_key = $printable_key{$index_key}; } +# if (!($printable_key) && ($printable_key{$cur_key})) +# { $printable_key = $printable_key{$cur_key}; } + # + # do not overwrite the printable_key if it contains an anchor + # + if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ )) + { $printable_key{$index_key} = $printable_key || $key; } +# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ )) +# { $printable_key{$cur_key} = $printable_key || $key; } + + $super_key = $cur_key; + } + # + # RRM + # page-ranges, from |( and |) and |see + # + if ($pageref) { + if ($pageref eq "\(" ) { + $pageref = ''; + $next .= " from "; + } elsif ($pageref eq "\)" ) { + $pageref = ''; + local($next) = $index{$index_key}; +# local($next) = $index{$cur_key}; + # $next =~ s/[\|] *$//; + $next =~ s/(\n )?\| $//; + $index{$index_key} = "$next to "; +# $index{$cur_key} = "$next to "; + } + } + + if ($pageref) { + $pageref =~ s/\s*$//g; # remove trailing spaces + if (!$pageref) { $pageref = ' ' } + $pageref =~ s/see/see <\/i> /g; + # + # RRM: 27 Dec 1996 + # check if $pageref corresponds to a style command. + # If so, apply it to the $words. + # + local($tmp) = "do_cmd_$pageref"; + if (defined &$tmp) { + $words = &$tmp("<#0#>$words<#0#>"); + $words =~ s/<\#[^\#]*\#>//go; + $pageref = ''; + } + } + # + # RRM: 25 May 1996 + # any \label in the pageref section will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($pageref) { + if ($pageref =~ /tex2html_anchor_mark/ ) { + $pageref =~ s/><\/A>$cross_ref_mark/ + $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_files{$label} = ''; # ???? RRM + if ($index_labels{$label}) { $ref_label = ''; } + else { $ref_label = $external_labels{$label} + unless ($ref_label = $ref_files{$label}); + } + '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo; + } + $pageref =~ s/<\#[^\#>]*\#>//go; + + if ($pageref eq ' ') { $index{$index_key}='@'; } + else { $index{$index_key} .= $pageref . "\n | "; } + } else { + local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words); + $thisref =~ s/\n//g; + $index{$index_key} .= $thisref."\n | "; + } + #print "\nREF: $sort_key : $index_key :$index{$index_key}"; + + #join('',"$anchor_invisible_mark<\/A>",$_); + + "$anchor_invisible_mark<\/A>"; +} + + +# KEC. -- Copied from makeidx.perl, then modified to do multiple indices. +# Feeds the index entries to the output. This is called for each index to be built. +# +# Generates a list of lookup keys for index entries, from both %printable_keys +# and %index keys. +# Sorts the keys according to index-sorting rules. +# Removes keys with a 0x01 token. (duplicates?) +# Builds a string to go to the index file. +# Adds the index entries to the string if they belong in this index. +# Keeps track of which index is being worked on, so only the proper entries +# are included. +# Places the index just built in to the output at the proper place. +{ my $index_number = 0; +sub add_real_idx { + print "\nDoing the index ... Index Number $index_number\n"; + local($key, @keys, $next, $index, $old_key, $old_html); + my ($idx_ref,$keyref); + # RRM, 15.6.96: index constructed from %printable_key, not %index + @keys = keys %printable_key; + + while (/$idx_mark/) { + # Get the index reference from what follows the $idx_mark and + # remove it from the string. + s/$idxmark\002(.*?)\002/$idxmark/; + $idx_ref = $1; + $index = ''; + # include non- makeidx index-entries + foreach $key (keys %index) { + next if $printable_key{$key}; + $old_key = $key; + if ($key =~ s/###(.*)$//) { + next if $printable_key{$key}; + push (@keys, $key); + $printable_key{$key} = $key; + if ($index{$old_key} =~ /HREF="([^"]*)"/i) { + $old_html = $1; + $old_html =~ /$dd?([^#\Q$dd\E]*)#/; + $old_html = $1; + } else { $old_html = '' } + $index{$key} = $index{$old_key} . $old_html."\n | "; + }; + } + @keys = sort makeidx_keysort @keys; + @keys = grep(!/\001/, @keys); + my $cnt = 0; + foreach $key (@keys) { + my ($keyref) = $key =~ /.*\002(.*)/; + next unless ($idx_ref eq $keyref); # KEC. + $index .= &add_idx_key($key); + $cnt++; + } + print "$cnt Index Entries Added\n"; + $index = '
'.$index unless ($index =~ /^\s*/); + $index_number++; # KEC. + if ($SHORT_INDEX) { + print "(compact version with Legend)"; + local($num) = ( $index =~ s/\ 50 ) { + s/$idx_mark/$preindex
\n$index\n<\/DL>$preindex/o; + } else { + s/$idx_mark/$preindex
\n$index\n<\/DL>/o; + } + } else { + s/$idx_mark/
\n$index\n<\/DL>/o; } + } +} +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# The bibliography and the index should be treated as separate sections +# in their own HTML files. The \bibliography{} command acts as a sectioning command +# that has the desired effect. But when the bibliography is constructed +# manually using the thebibliography environment, or when using the +# theindex environment it is not possible to use the normal sectioning +# mechanism. This subroutine inserts a \bibliography{} or a dummy +# \textohtmlindex command just before the appropriate environments +# to force sectioning. +sub add_bbl_and_idx_dummy_commands { + local($id) = $global{'max_id'}; + + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg; + ## if ($bbl_cnt == 1) { + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo; + #} + $global{'max_id'} = $id; + # KEC. Modified to global substitution to place multiple index tokens. + s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go; + # KEC. Modified to pick up the optional argument to \printindex + s/[\\]printindex\s*(\[.*?\])?/ + do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego; + &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands); +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# For each textohtmlindex mark found, determine the index titles and headers. +# We place the index ref in the header so the proper index can be generated later. +# For the default index, the index ref is blank. +# +# One problem is that this routine is called twice.. Once for processing the +# command as originally seen, and once for processing the command when +# doing the name for the index file. We can detect that by looking at the +# id numbers (or ref) surrounding the \theindex command, and not incrementing +# index_number unless a new id (or ref) is seen. This has the side effect of +# having to unconventionally start the index_number at -1. But it works. +# +# Gets the title from the list of indices. +# If this is the first index, save the title in $first_idx_file. This is what's referenced +# in the navigation buttons. +# Increment the index_number for next time. +# If the indexname command is defined or a newcommand defined for indexname, do it. +# Save the index TITLE in the toc +# Save the first_idx_file into the idxfile. This goes into the nav buttons. +# Build index_labels if needed. +# Create the index headings and put them in the output stream. + +{ my $index_number = 0; # Will be incremented before use. + my $first_idx_file; # Static + my $no_increment = 0; + +sub do_cmd_textohtmlindex { + local($_) = @_; + my ($idxref,$idxnum,$index_name); + + # We get called from make_name with the first argument = "\001noincrement". This is a sign + # to not increment $index_number the next time we are called. We get called twice, once + # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name + # but doesn't use the result so we get called a second time by process_command. This works fine + # except for cases where there are multiple indices except if they aren't named, which is the case + # when the index is inserted by an include command in latex. In these cases we are only able to use + # the index number to decide which index to draw from, and we don't know how to increment that index + # number if we get called a variable number of times for the same index, as is the case between + # making html (one output file) and web (multiple output files) output formats. + if (/\001noincrement/) { + $no_increment = 1; + return; + } + + # Remove (but save) the index reference + s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e; + + # If we have an $idxref, the index name was specified. In this case, we have all the + # information we need to carry on. Otherwise, we need to get the idxref + # from the $index_number and set the name to "Index". + if ($idxref) { + $index_name = $indices{'title'}{$idxref}; + } else { + if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) { + $index_name = $indices{'title'}{$idxref}; + } else { + $idxref = ''; + $index_name = "Index"; + } + } + + $idx_title = "Index"; # The name displayed in the nav bar text. + + # Only set $idxfile if we are at the first index. This will point the + # navigation panel to the first index file rather than the last. + $first_idx_file = $CURRENT_FILE if ($index_number == 0); + $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar. + $toc_sec_title = $index_name; # Index link text in the toc. + $TITLE = $toc_sec_title; # Title for this index, from which its filename is built. + if (%index_labels) { &make_index_labels(); } + if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); } + else { $preindex = ''; } + local $idx_head = $section_headings{'textohtmlindex'}; + local($heading) = join('' + , &make_section_heading($TITLE, $idx_head) + , $idx_mark, "\002", $idxref, "\002" ); + local($pre,$post) = &minimize_open_tags($heading); + $index_number++ unless ($no_increment); + $no_increment = 0; + join('',"
\n" , $pre, $_); +} +} + +# Returns an index key, given the key passed as the first argument. +# Not modified for multiple indices. +sub add_idx_key { + local($key) = @_; + local($index, $next); + if (($index{$key} eq '@' )&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { $index .= "

\n
".&print_key."\n
"; } + else { $index .= "

\n
".&print_key."\n
"; } + } elsif (($index{$key})&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { + $next = "
".&print_key."\n : ". &print_idx_links; + } else { + $next = "
".&print_key."\n
". &print_idx_links; + } + $index .= $next."\n"; + $index_printed{$key} = 1; + } + + if ($sub_index{$key}) { + local($subkey, @subkeys, $subnext, $subindex); + @subkeys = sort(split("\004", $sub_index{$key})); + if ($SHORT_INDEX) { + $index .= "
".&print_key unless $index_printed{$key}; + $index .= "
\n"; + } else { + $index .= "
".&print_key."\n
" unless $index_printed{$key}; + $index .= "
\n"; + } + foreach $subkey (@subkeys) { + $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey}); + } + $index .= "
\n"; + } + return $index; +} + +1; # Must be present as the last line. diff --git a/docs/manuals/fr/catalog/internaldb.tex b/docs/manuals/fr/catalog/internaldb.tex new file mode 100644 index 00000000..65cd0ea0 --- /dev/null +++ b/docs/manuals/fr/catalog/internaldb.tex @@ -0,0 +1,76 @@ +%% +%% + +\chapter{The internal database is not supported, please do not +use it.} +\label{InternalDbChapter} +\index[general]{Use it!The internal database is not supported please +do not } +\index[general]{The internal database is not supported, please do not +use it. } + +\section{Internal Bacula Database} +\index[general]{Internal Bacula Database } +\index[general]{Database!Internal Bacula } + +Previously it was intended to be used primarily by Bacula developers for +testing; although SQLite is also a good choice for this. We do not recommend +its use in general. + +This database is simplistic in that it consists entirely of Bacula's internal +structures appended sequentially to a file. Consequently, it is in most cases +inappropriate for sites with many clients or systems with large numbers of +files, or long-term production environments. + +Below, you will find a table comparing the features available with SQLite and +MySQL and with the internal Bacula database. At the current time, you cannot +dynamically switch from one to the other, but must rebuild the Bacula source +code. If you wish to experiment with both, it is possible to build both +versions of Bacula and install them into separate directories. + +\addcontentsline{lot}{table}{SQLite vs MySQL Database Comparison} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{1}{|c| }{\bf Feature } & \multicolumn{1}{c| }{\bf SQLite or MySQL + } & \multicolumn{1}{c| }{\bf Bacula } \\ + \hline +{Job Record } & {Yes } & {Yes } \\ + \hline +{Media Record } & {Yes } & {Yes } \\ + \hline +{FileName Record } & {Yes } & {No } \\ + \hline +{File Record } & {Yes } & {No } \\ + \hline +{FileSet Record } & {Yes } & {Yes } \\ + \hline +{Pool Record } & {Yes } & {Yes } \\ + \hline +{Client Record } & {Yes } & {Yes } \\ + \hline +{JobMedia Record } & {Yes } & {Yes } \\ + \hline +{List Job Records } & {Yes } & {Yes } \\ + \hline +{List Media Records } & {Yes } & {Yes } \\ + \hline +{List Pool Records } & {Yes } & {Yes } \\ + \hline +{List JobMedia Records } & {Yes } & {Yes } \\ + \hline +{Delete Pool Record } & {Yes } & {Yes } \\ + \hline +{Delete Media Record } & {Yes } & {Yes } \\ + \hline +{Update Pool Record } & {Yes } & {Yes } \\ + \hline +{Implement Verify } & {Yes } & {No } \\ + \hline +{MD5 Signatures } & {Yes } & {No } +\\ \hline + +\end{longtable} + +In addition, since there is no SQL available, the Console commands: {\bf +sqlquery}, {\bf query}, {\bf retention}, and any other command that directly +uses SQL are not available with the Internal database. diff --git a/docs/manuals/fr/catalog/latex2html-init.pl b/docs/manuals/fr/catalog/latex2html-init.pl new file mode 100644 index 00000000..14b5c319 --- /dev/null +++ b/docs/manuals/fr/catalog/latex2html-init.pl @@ -0,0 +1,10 @@ +# This file serves as a place to put initialization code and constants to +# affect the behavior of latex2html for generating the bacula manuals. + +# $LINKPOINT specifies what filename to use to link to when creating +# index.html. Not that this is a hard link. +$LINKPOINT='"$OVERALL_TITLE"'; + + +# The following must be the last line of this file. +1; diff --git a/docs/manuals/fr/catalog/mysql.tex b/docs/manuals/fr/catalog/mysql.tex new file mode 100644 index 00000000..75cc6f0e --- /dev/null +++ b/docs/manuals/fr/catalog/mysql.tex @@ -0,0 +1,286 @@ +%% +%% + +\chapter{Installing and Configuring MySQL} +\label{MySqlChapter} +\index[general]{MySQL!Installing and Configuring } +\index[general]{Installing and Configuring MySQL } + +\section{Installing and Configuring MySQL -- Phase I} +\index[general]{Installing and Configuring MySQL -- Phase I } +\index[general]{Phase I!Installing and Configuring MySQL -- } + +If you use the ./configure \verb:--:with-mysql=mysql-directory statement for +configuring {\bf Bacula}, you will need MySQL version 4.1 or later installed +in the {\bf mysql-directory}. If you are using one of the new modes such as +ANSI/ISO compatibility, you may experience problems. + +If MySQL is installed in the standard system location, you need only enter +{\bf \verb:--:with-mysql} since the configure program will search all the +standard locations. If you install MySQL in your home directory or some +other non-standard directory, you will need to provide the full path to it. + +Installing and Configuring MySQL is not difficult but can be confusing the +first time. As a consequence, below, we list the steps that we used to install +it on our machines. Please note that our configuration leaves MySQL without +any user passwords. This may be an undesirable situation if you have other +users on your system. + +The notes below describe how to build MySQL from the source tar files. If +you have a pre-installed MySQL, you can return to complete the installation +of Bacula, then come back to Phase II of the MySQL installation. If you +wish to install MySQL from rpms, you will probably need to install +the following: + +\footnotesize +\begin{verbatim} +mysql-.rpm +mysql-server-.rpm +mysql-devel-.rpm +\end{verbatim} +\normalsize +The names of the packages may vary from distribution to +distribution. It is important to have the devel package loaded as +it contains the libraries and header files necessary to build +Bacula. There may be additional packages that are required to +install the above, for example, zlib and openssl. + +Once these packages are installed, you will be able to build Bacula (using +the files installed with the mysql package, then run MySQL using the +files installed with mysql-server. If you have installed MySQL by rpms, +please skip Phase I below, and return to complete the installation of +Bacula, then come back to Phase II of the MySQL installation when indicated +to do so. + +Beginning with Bacula version 1.31, the thread safe version of the +MySQL client library is used, and hence you should add the {\bf +\verb:--:enable-thread-safe-client} option to the {\bf +./configure} as shown below: + +\begin{enumerate} +\item Download MySQL source code from + \elink{www.mysql.com/downloads}{http://www.mysql.com/downloads} + +\item Detar it with something like: + + {\bf tar xvfz mysql-filename} + +Note, the above command requires GNU tar. If you do not have GNU tar, a +command such as: + +{\bf zcat mysql-filename | tar xvf - } + +will probably accomplish the same thing. + +\item cd {\bf mysql-source-directory} + + where you replace {\bf mysql-source-directory} with the directory name where + you put the MySQL source code. + +\item ./configure \verb:--:enable-thread-safe-client \verb:--:prefix=mysql-directory + + where you replace {\bf mysql-directory} with the directory name where you + want to install mysql. Normally for system wide use this is /usr/local/mysql. + In my case, I use \~{}kern/mysql. + +\item make + + This takes a bit of time. + +\item make install + + This will put all the necessary binaries, libraries and support files into + the {\bf mysql-directory} that you specified above. + +\item ./scripts/mysql\_install\_db + + This will create the necessary MySQL databases for controlling user access. +Note, this script can also be found in the {\bf bin} directory in the +installation directory + +\end{enumerate} + +The MySQL client library {\bf mysqlclient} requires the gzip compression +library {\bf libz.a} or {\bf libz.so}. If you are using rpm packages, these +libraries are in the {\bf libz-devel} package. On Debian systems, you will +need to load the {\bf zlib1g-dev} package. If you are not using rpms or debs, +you will need to find the appropriate package for your system. + +At this point, you should return to completing the installation of {\bf +Bacula}. Later after Bacula is installed, come back to this chapter to +complete the installation. Please note, the installation files used in the +second phase of the MySQL installation are created during the Bacula +Installation. + +\label{mysql_phase2} +\section{Installing and Configuring MySQL -- Phase II} +\index[general]{Installing and Configuring MySQL -- Phase II } +\index[general]{Phase II!Installing and Configuring MySQL -- } + +At this point, you should have built and installed MySQL, or already have a +running MySQL, and you should have configured, built and installed {\bf +Bacula}. If not, please complete these items before proceeding. + +Please note that the {\bf ./configure} used to build {\bf Bacula} will need to +include {\bf \verb:--:with-mysql=mysql-directory}, where {\bf mysql-directory} is the +directory name that you specified on the ./configure command for configuring +MySQL. This is needed so that Bacula can find the necessary include headers +and library files for interfacing to MySQL. + +{\bf Bacula} will install scripts for manipulating the database (create, +delete, make tables etc) into the main installation directory. These files +will be of the form *\_bacula\_* (e.g. create\_bacula\_database). These files +are also available in the \lt{}bacula-src\gt{}/src/cats directory after +running ./configure. If you inspect create\_bacula\_database, you will see +that it calls create\_mysql\_database. The *\_bacula\_* files are provided for +convenience. It doesn't matter what database you have chosen; +create\_bacula\_database will always create your database. + +Now you will create the Bacula MySQL database and the tables that Bacula uses. + + +\begin{enumerate} +\item Start {\bf mysql}. You might want to use the {\bf startmysql} script + provided in the Bacula release. + +\item cd \lt{}install-directory\gt{} + This directory contains the Bacula catalog interface routines. + +\item ./grant\_mysql\_privileges + This script creates unrestricted access rights for the user {\bf bacula}. + You may want to modify it to suit your situation. Please + note that none of the userids, including root, are password protected. + If you need more security, please assign a password to the root user + and to bacula. The program {\bf mysqladmin} can be used for this. + +\item ./create\_mysql\_database + This script creates the MySQL {\bf bacula} database. The databases you + create as well as the access databases will be located in + \lt{}install-dir\gt{}/var/ in a subdirectory with the name of the + database, where \lt{}install-dir\gt{} is the directory name that you + specified on the {\bf \verb:--:prefix} option. This can be important to + know if you want to make a special backup of the Bacula database or to + check its size. + +\item ./make\_mysql\_tables + This script creates the MySQL tables used by {\bf Bacula}. +\end{enumerate} + +Each of the three scripts (grant\_mysql\_privileges, create\_mysql\_database +and make\_mysql\_tables) allows the addition of a command line argument. This +can be useful for specifying the user and or password. For example, you might +need to add {\bf -u root} to the command line to have sufficient privilege to +create the Bacula tables. + +To take a closer look at the access privileges that you have setup with the +above, you can do: + +\footnotesize +\begin{verbatim} +mysql-directory/bin/mysql -u root mysql +select * from user; +\end{verbatim} +\normalsize + +\section{Re-initializing the Catalog Database} +\index[general]{Database!Re-initializing the Catalog } +\index[general]{Re-initializing the Catalog Database } + +After you have done some initial testing with {\bf Bacula}, you will probably +want to re-initialize the catalog database and throw away all the test Jobs +that you ran. To do so, you can do the following: + +\footnotesize +\begin{verbatim} + cd + ./drop_mysql_tables + ./make_mysql_tables +\end{verbatim} +\normalsize + +Please note that all information in the database will be lost and you will be +starting from scratch. If you have written on any Volumes, you must write an +end of file mark on the volume so that Bacula can reuse it. Do so with: + +\footnotesize +\begin{verbatim} + (stop Bacula or unmount the drive) + mt -f /dev/nst0 rewind + mt -f /dev/nst0 weof +\end{verbatim} +\normalsize + +Where you should replace {\bf /dev/nst0} with the appropriate tape drive +device name for your machine. + +\section{Linking Bacula with MySQL} +\index[general]{Linking Bacula with MySQL } +\index[general]{MySQL!Linking Bacula with } +\index[general]{Upgrading} + +After configuring Bacula with + +./configure \verb:--:enable-thread-safe-client \verb:--:prefix=\lt{}mysql-directory\gt{} +where \lt{}mysql-directory\gt{} is in my case {\bf /home/kern/mysql}, you may +have to configure the loader so that it can find the MySQL shared libraries. +If you have previously followed this procedure and later add the {\bf +\verb:--:enable-thread-safe-client} options, you will need to rerun the {\bf +ldconfig} program shown below. If you put MySQL in a standard place such as +{\bf /usr/lib} or {\bf /usr/local/lib} this will not be necessary, but in my +case it is. The description that follows is Linux specific. For other +operating systems, please consult your manuals on how to do the same thing: + +First edit: {\bf /etc/ld.so.conf} and add a new line to the end of the file +with the name of the mysql-directory. In my case, it is: + +/home/kern/mysql/lib/mysql then rebuild the loader's cache with: + +/sbin/ldconfig If you upgrade to a new version of {\bf MySQL}, the shared +library names will probably change, and you must re-run the {\bf +/sbin/ldconfig} command so that the runtime loader can find them. + +Alternatively, your system my have a loader environment variable that can be +set. For example, on a Solaris system where I do not have root permission, I +use: + +LD\_LIBRARY\_PATH=/home/kern/mysql/lib/mysql + +Finally, if you have encryption enabled in MySQL, you may need to add {\bf +-lssl -lcrypto} to the link. In that case, you can either export the +appropriate LDFLAGS definition, or alternatively, you can include them +directly on the ./configure line as in: + +\footnotesize +\begin{verbatim} +LDFLAGS="-lssl -lcyrpto" \ + ./configure \ + +\end{verbatim} +\normalsize + +\section{Installing MySQL from RPMs} +\index[general]{MySQL!Installing from RPMs} +\index[general]{Installing MySQL from RPMs} +If you are installing MySQL from RPMs, you will need to install +both the MySQL binaries and the client libraries. The client +libraries are usually found in a devel package, so you must +install: + +\footnotesize +\begin{verbatim} + mysql + mysql-devel +\end{verbatim} +\normalsize + +This will be the same with most other package managers too. + +\section{Upgrading MySQL} +\index[general]{Upgrading MySQL } +\index[general]{Upgrading!MySQL } +\index[general]{Upgrading} +If you upgrade MySQL, you must reconfigure, rebuild, and re-install +Bacula otherwise you are likely to get bizarre failures. If you +install from rpms and you upgrade MySQL, you must also rebuild Bacula. +You can do so by rebuilding from the source rpm. To do so, you may need +to modify the bacula.spec file to account for the new MySQL version. diff --git a/docs/manuals/fr/catalog/postgresql.tex b/docs/manuals/fr/catalog/postgresql.tex new file mode 100644 index 00000000..9bbf8203 --- /dev/null +++ b/docs/manuals/fr/catalog/postgresql.tex @@ -0,0 +1,457 @@ +%% +%% + +\chapter{Installer et configurer PostgreSQL} +\label{_ChapterStart10} +\index[general]{PostgreSQL!Installer et configurer } +\index[general]{Installer et configurer PostgreSQL } +\addcontentsline{toc}{section}{Installer et configurer PostgreSQL} + +\section{Installer et configurer PostgreSQL -- Phase I} +\index[general]{Installer et configurer PostgreSQL -- Phase I } +\index[general]{Phase I!Installer et configurer PostgreSQL -- } +\addcontentsline{toc}{section}{Installer et configurer PostgreSQL -- Phase +I} + +Attention !!! Si vous envisagez d'utiliser PostgreSQL, vous devriez +\^etre conscient de la philosophie des mises \`a jour de PostgreSQL qui +peut \^etre d\'estabilisant dans un environnement de +production. En gros, pour chaque mise \`a jour vers une version majeure, +vous devez exporter vos bases de donn\'ees au format ASCII, faire la +mise \`a jour, et recharger vos bases de donn\'ees. Ceci est d\^u au \`a des +mises \`a jour fr\'equentes du "format de donn\'ees" d'une version \`a l'autre, +et aucun outil n'est fourni pour effectuer la conversion automatiquement. +Si vous omettez d'exporter vos bases au format ASCII, elles peuvent +devenir compl\`etement inutiles si aucun des nouveaux outils ne peut y +acc\'eder en raison d'un changement de format, auquel cas le serveur +PostgreSQL sera dans l'incapacit\'e de d\'emarrer. + +Si vous avez utilis\'e l'option {\bf ./configure +\verb{--{with-postgresql=PostgreSQL-Directory} pour configurer {\bf Bacula}, vous +avez besoin d'installer la version 7.3 ou sup\'erieure de PostgreSQL. +ATTENTION! Les versions pr\'ealables \`a la 7.3 ne fonctionnent pas avec +Bacula. Si PostgreSQL est install\'e dans ses r\'epertoires sandards, seule +l'option {\bf \verb{--{with-postgresql} est n\'ecessaire, le programme de +configuration scrutant tous les r\'epertoires standards. Si PostgreSQL est +install\'e dans votre r\'epertoire de travail ou dans un r\'epertoire +atypique, il faut pr\'eciser l'option {\bf \verb{--{with-postgresql} suivie du +r\'epertoire {\it ad hoc}. + +Installer et configurer PostgreSQL n'est pas compliqu\'e mais peut \^etre +d\'eroutant la premi\`ere fois. Si vous pr\'ef\'erez, vous pouvez utiliser le +paquet de votre distribution. Les paquets binaires sont disponibles sur la +plupart des mirroirs de PostgreSQL. + +Si vous pr\'ef\'erez installer PostgreSQL \`a partir des sources, nous vous +recommandons de suivre les instructions de la +\elink{documentation PostgreSQL}{http://www.postgresql.org/docs/}. + +Si vous utilisez PostgreSQL pour FreeBSD, +\elink{cet article}{http://www.freebsddiary.org/postgresql.php} vous sera peut +\^etre utile. M\^eme si vous n'utilisez pas FreeBSD, l'article contient des +informations utiles \`a la configuration et au param\'etrage de PostgreSQL. + +Apr\`es l'installation de PostgreSQL, terminez l'installation de {\bf Bacula}. +Ensuite, quand Bacula sera install\'e, reprenez ce chapitre pour terminer +l'installation. Notez que les fichiers d'installation utilis\'es dans cette +seconde phase de l'installation de PostgreSQL sont cr\'e\'es durant +l'installation de Bacula. +\label{PostgreSQL_phase2} + +\section{Installer et configurer PostgreSQL -- Phase II} +\index[general]{Phase II!Installer et configurer PostgreSQL -- } +\index[general]{Installer et configurer PostgreSQL -- Phase II } +\addcontentsline{toc}{section}{Installer et configurer PostgreSQL -- Phase +II} + +Si vous en \^etes l\`a, vous avez construit et install\'e PostgreSQL, ou vous +aviez d\'ej\`a un serveur PostgreSQL existant et vous avez configur\'e et +install\'e {\bf Bacula}. Dans le cas contraire, nous vous invitons \`a le +faire avant de poursuivre. + +Notez bien que la commande {\bf ./configure} utilis\'ee pour +construire {\bf Bacula} n\'ecessite d'ajouter l'option {\bf +\verb{--{with-postgresql=repertoire\_de\_PostgreSQL}, o\`u {\bf +repertoire\_de\_PostgreSQL} sp\'ecifie le chemin de PostgreSQL indiqu\'e \`a +la commande ./configure. (si vous n'avez pas sp\'ecifi\'e de r\'epertoire ou +si PostgreSQL est install\'e dans son r\'epertoire par d\'efaut, cette option +n'est pas n\'ecessaire). Cette option est n\'ecessaire pour que Bacula puisse +trouver les fichiers d'en-t\^ete et les librairies d'interface \`a PostgreSQL. + + +{\bf Bacula} installe les scripts pour la gestion de la base de donn\'ees +(cr\'eer, d\'etruire, cr\'eer les tables, etc.) dans le r\'epertoire principal +de l'installation. Ces fichiers sont de la forme *\_bacula\_* (par exemple +create\_bacula\_database). Ces fichiers sont \'egalement disponibles dans le +r\'epertoire \lt{}bacula-src\gt{}/src/cats apr\`es que la commande ./configure +ait \'et\'e lanc\'ee. Si vous consultez le fichier create\_bacula\_database, +vous verrez qu'il fait appel \`a create\_postgresql\_database. Les fichiers +*\_bacula\_* sont fournis pour faciliter les choses. Peu importe la base de +donn\'ees choisie, create\_bacula\_database cr\'eera la base de donn\'ees. + +Maintenant vous allez cr\'eer la base de donn\'ees PostgreSQL et les tables +utilis\'ees par Bacula. On pr\'esume dans la suite que votre serveur +PostgreSQL fonctionne. Vous devez ex\'ecuter les diff\'erentes \'etapes +ci-dessous en tant qu'utilisateur autoris\'e \`a cr\'eer des bases. Ceci peut +\^etre fait avec l'utilisateur PostgreSQL (sur la plupart des syst\`emes il +s'agit de pgsql. NDT: sur debian il s'agit de postgres) + +\begin{enumerate} +\item cd \lt{}r\'epertoire\_d\_installation\gt{} + + Ce r\'epertoire contient le catalogue des routines d'interfaces. + +\item ./create\_bacula\_database + + Ce script cr\'e\'e le catalogue {\bf bacula} PostgreSQL. S'il \'echoue, + c'est probablement que vous n'avez pas les droits requis sur la + base de donn\'ees. Sur la plupart des syst\`emes, le propri\'etaire de + la base de donn\'ees est {\bf pgsql}, et sur d'autres tels que RedHat ou + Fedora, c'est {\bf postgres}. Vous pouvez d\'eterminer lequel en examinant + le fichier /etc/passwd. Pour cr\'eer un nouvel utilisateur avec votre nom + ou le nom {\bf bacula}, vous pouvez faire ce qui suit : + +\begin{verbatim} + su + (entrez le mot de passe root) + su pgsql (ou postgres) + createuser kern (ou peut-\^etre bacula) + Shall the new user be allowed to create databases? (y/n) y + Shall the new user be allowed to create more new users? (y/n) (choisissez ce que vous voulez) + exit +\end{verbatim} + + + A ce stade, vous devriez pouvoir ex\'ecuter la commande ./create\_bacula\_database + +\item ./make\_bacula\_tables + + Cr\'e\'ee les tables utilis\'ees par {\bf Bacula}. +\item ./grant\_bacula\_privileges + + Cr\'e\'ee l'utilisateur de la base de donn\'ees {\bf bacula} avec des droits +d'acc\`es restreints. Vous pouvez modifier ce script pour cadrer avec votre +propre configuration. Attention, cette base n'est pas prot\'eg\'ee par un mot +de passe. + +\end{enumerate} + +Chacun de ces scripts (create\_bacula\_database, make\_bacula\_tables et +grant\_bacula\_privileges) permet l'ajout d'arguments en ligne de commande. +Ceci peut \^etre utile pour sp\'ecifier le nom de l'utilisateur. Par exemple, +vous pouvez avoir besoin d'ajouter {\bf -h nom\_d\_hote} \`a la ligne de +commande pour sp\'ecifier le serveur de base de donn\'ees distant. + +Pour avoir un bon aper\c{c}u des droits d'acc\`es que vous avez sp\'ecifi\'e +vous pouvez utiliser la commande + +\footnotesize +\begin{verbatim} + +repertoire_de_PostgreSQL/bin/psql --command \\dp bacula +\end{verbatim} +\normalsize + +J'ai rencontr\'e un probl\`eme de permissions avec le mot de passe. J'ai finalement +du modifier mon fichier {\bf pg\_hba.conf} (situ\'e dans /var/lib/pgsql/data sur ma +machine) : + +\footnotesize +\begin{verbatim} +de + local all all ident sameuser +vers + local all all trust sameuser +\end{verbatim} +\normalsize + +Ceci a r\'esolu le probl\`eme pour moi, mais ce n'est pas pas forc\'ement une bonne +chose du point de vue de la s\'ecurit\'e, mais j'ai ainsi pu ex\'ecuter mes scripts de +r\'egression sans mot de passe. + +Un moyen plus s\'ecuris\'e pour l'authentification aupr\`es de la base de donn\'ees +consiste \`a utiliser le hachage MD5 des mots de passe. Pour cela, \'editez les +fichier {\bf pg\_hba.conf}, et ajoutez ajoutez ce qui suit juste avant les lignes +"local" et "host" existantes : + +\footnotesize +\begin{verbatim} + local bacula bacula md5 +\end{verbatim} +\normalsize + +Puis red\'emarrez le {\it daemon} Postgres (la plupart du temps, avec + "/etc/init.d/postgresql restart") pour activer cette nouvelle r\`egle +d'authentification. + +Ensuite, en tant qu'administrateur Postgres (connectez-vous en tant +qu'utilisateur postgres ou en utilisant {\bf su} pour devenir root, puis + {\bf su postgres}), ajoutez un mot de passe \`a la base de donn\'ees bacula +pour l'utilisateur bacula avec les commandes suivantes : + +\footnotesize +\begin{verbatim} + \$ psql bacula + bacula=# alter user bacula with password 'secret'; + ALTER USER + bacula=# \\q +\end{verbatim} +\normalsize + +Enfin, il vous faudra ajouter ce mot de passe en deux endroits du fichier +bacula-dir.conf : au niveau de la ressource Catalog et au niveau de la +directive RunBeforeJob de la ressource Job BackupCatalog. Avec les mots de +passe en place, ces deux lignes devraient ressembler \`a ceci : + +\footnotesize +\begin{verbatim} + dbname = bacula; user = bacula; password = "secret" + ... and ... + RunBeforeJob = "/etc/make_catalog_backup bacula bacula secret" +\end{verbatim} +\normalsize + +Naturellement, vous devriez choisir un meilleur mot de passe, et vous assurer +que le fichier bacula-dir.conf qui contient ce mot de passe n'est lisible +que par root. + +M\^eme avec ces restrictions, il reste un probl\`eme de s\'ecurit\'e avec cette approche : +sur certaines plateformes, la variable d'environnement utilis\'ee pour soumettre le +mot de passe \`a Postgres est disponible pour tout utilisateur +local du syst\`eme. Pour supprimer ce probl\`eme, l'\'equipe Postgres a d\'ecr\'et\'e +obsol\`ete ce m\'ecanisme de passage de mot de passe par variable d'environnement et +recommande d'utiliser un fichier .pgpass. Pour utiliser ce m\'ecanisme, cr\'eez un fichier +nomm\'e .pgpass vcontenant une simple ligne : + +\footnotesize +\begin{verbatim} + localhost:5432:bacula:bacula:secret +\end{verbatim} +\normalsize + +Ce fichier devrait \^etre copi\'e dans les r\'epertoires personnels (NDT : home directories) +de tous les comptes susceptibles d'avoir besoin d'acc\'eder \`a la base de donn\'ees : +typiquement, il s'agit de root, bacula et tout utilisateur de la console Bacula. Les fichiers +doivent appartenir aux utilisateur et groupe correspondant : root:root pour la copie +dans ~root, etc. Les permissions doivent \^etre positionn\'ees \`a 600 pour limiter +l'acc\`es au propri\'etaire du fichier. + +\section{R\'einitialiser la base des catalogues (de sauvegardes)} +\index[general]{R\'einitialiser la base des catalogues (de sauvegardes) } +\index[general]{Sauvegardes!R\'einitialiser la base des catalogues de } +\addcontentsline{toc}{section}{R\'einitialiser la base des catalogues (de +sauvegardes)} + +Apr\`es avoir fait un certain nombre de tests avec {\bf Bacula}, vous aurez +tr\`es certainement envie de nettoyer le catalogue des sauvegardes et faire +dispara{\^\i}tre tous les travaux de tests que vous avez lanc\'es. Pour ce +faire, vous pouvez ex\'ecuter les commandes suivantes: + +\footnotesize +\begin{verbatim} + + cd + ./drop_bacula_tables + ./make_bacula_tables + ./grant_bacula_privileges +\end{verbatim} +\normalsize + +Attention! Toutes les informations contenues dans cette base seront perdues et +vous repartirez de z\'ero. Si vous avez \'ecrit sur certains volumes (m\'edia +de sauvegarde), vous devrez \'ecrire une marque de fin de fichier (EOF) sur +chacun d'eux afin que {\bf Bacula} puisse les r\'eutiliser. Pour ce faire: + +\footnotesize +\begin{verbatim} + + (arr\^eter Baula ou demonter les volumes) + mt -f /dev/nst0 rewind + mt -f /dev/nst0 weof +\end{verbatim} +\normalsize + +o\`u vous devrez remplacer {\bf /dev/nst0} par le chemin appropri\'e de votre +lecteur de sauvegarde. + +\section{Installer PostgreSQL avec les RPMs} +\index[general]{PostgreSQL!Installer avec les RPMs} +\index[general]{Installer PostgreSQL avec les RPMs} +\addcontentsline{toc}{section}{Installer PostgreSQL avec les RPMs} +Si vous installez PostgreSQL avec les RPMs, il vous faut installer les +binaires PostgreSQL ainsi que les librairies clientes. Ces derni\`eres font +g\'en\'eralement partie de paquetages de d\'eveloppement, aussi vous devez installer : + +\footnotesize +\begin{verbatim} + postgresql + postgresql-devel +\end{verbatim} +\normalsize + +Il en va de m\^eme avec la plupart des gestionnaires de paquetages. + +\section{Migrer de MySQL \`a PostgreSQL} +\index[general]{Migrer de MySQL \`a PostgreSQL } +\index[general]{PostgreSQL!Migrer de MySQL \`a } +\addcontentsline{toc}{section}{Migrer de MySQL \`a PostgreSQL} + +La proc\'edure de migration pr\'esent\'ee ici \`a fonctionn\'e pour Norm +Dressler \lt{}ndressler at dinmar dot com\gt{} + +Ce process a \'et\'e test\'e en utilisant les versions suivantes des +diff\'erents logiciels: + +\begin{itemize} +\item Linux Mandrake 10/Kernel 2.4.22-10 SMP +\item MySQL Ver 12.21 Distrib 4.0.15, pour mandrake-linux-gnu (i586) +\item PostgreSQL 7.3.4 +\item Bacula 1.34.5 + \end{itemize} + +ATTENTION! Par pr\'ecaution, r\'ealisez une sauvegarde compl\`ete de vos +syst\`emes avant de proc\'eder \`a cette migration. + +\begin{enumerate} +\item Arr\^etez bacula (cd /etc/bacula;./bacula stop) +\item Lancez la commande pour extraire les donn\'ees de votre base MySQL: + + \footnotesize +\begin{verbatim} + + mysqldump -f -t -n >bacula-backup.dmp + +\end{verbatim} +\normalsize + +\item Faites une sauvegarde de votre r\'epertoire /etc/bacula (mais laisser + l'original en place ). +\item Allez dans le r\'epertoire source de {\bf Bacula} et reconstruisez le en + incluant le support PostgreSQL au lieu de celui de MySQL . V\'erifiez que le + fichier config.log de votre configuration originale et remplacez enable-mysql +par enable-postgresql. +\item Recompilez Bacula avec la commande make et si tout se passe correctement + lancez un "make install". +\item Arr\^etez MySQL. +\item Lancez PostgreSQL sur votre syst\`eme. +\item Cr\'eez un utilisateur {\bf Bacula} dans Postgres avec la commande + "createuser". En fonction de votre installation, vous serez peut \^etre + amen\'e \`a faire un "su" vers l'utilisateur ad\'equat (NDT: su postgres). +\item Verifiez que le fichier pg\_hba.conf (NdT sur Debian: + /etc/postgres/pg\_hba.conf) contient les permissions ad\'equates pour + permettre \`a {\bf Bacula} d'acc\'eder au serveur. Le mien contient les +informations suivantes, et il est situ\'e sur un r\'eseau s\'ecuris\'e, + +\footnotesize +\begin{verbatim} + +local all all trust + +host all all 127.0.0.1 255.255.255.255 trust + +ATTENTION: vous devez red\'emmarer PostgreSQL si vous faites des changements dans ce fichier. + +\end{verbatim} +\normalsize + +\item Allez dans le r\'epertoire /etc/bacula et pr\'eparez la base de + donn\'ees avec les commandes suivantes: + +\footnotesize +\begin{verbatim} + +./create_postgresql_database + +./make_postgresql_tables + +./grant_postgresql_privileges + +\end{verbatim} +\normalsize + +\item Verifiez que vous avez acc\`es \`a la base de donn\'ees: + + \footnotesize +\begin{verbatim} + +psql -Ubacula bacula + +\end{verbatim} +\normalsize + +Vous ne devriez avoir aucune erreur. +\item Chargez la base PostgreSQL avec l'extraction MySQL gr\^ace \`a la + commande: + +\footnotesize +\begin{verbatim} + +psql -Ubacula bacula + +\end{verbatim} +\normalsize + +\item R\'eindexez vos tables avec les commandes suivantes: + + \footnotesize +\begin{verbatim} + +psql -Ubacula bacula + +SELECT SETVAL('basefiles_baseid_seq', (SELECT +MAX(baseid) FROM basefiles)); + +SELECT SETVAL('client_clientid_seq', (SELECT +MAX(clientid) FROM client)); + +SELECT SETVAL('file_fileid_seq', (SELECT MAX(fileid) +FROM file)); + +SELECT SETVAL('filename_filenameid_seq', (SELECT +MAX(filenameid) FROM filename)); + +SELECT SETVAL('fileset_filesetid_seq', (SELECT +MAX(filesetid) FROM fileset)); + +SELECT SETVAL('job_jobid_seq', (SELECT MAX(jobid) FROM job)); + +SELECT SETVAL('jobmedia_jobmediaid_seq', (SELECT +MAX(jobmediaid) FROM jobmedia)); + +SELECT SETVAL('media_mediaid_seq', (SELECT MAX(mediaid) FROM media)); + +SELECT SETVAL('path_pathid_seq', (SELECT MAX(pathid) FROM path)); + +SELECT SETVAL('pool_poolid_seq', (SELECT MAX(poolid) FROM pool)); + +\end{verbatim} +\normalsize + +\item Parvenu ici, lancez {\bf Bacula}, v\'erifiez votre librairie et + faites un test pour valider que tout s'est bien d\'eroul\'e. +\end{enumerate} + +\section{Mettre \`a jour PostgreSQL} +\index[general]{Mettre \`a jour PostgreSQL } +\index[general]{Mettre \`a jour!PostgreSQL } +\addcontentsline{toc}{section}{Mettre \`a jour PostgreSQL} +Si vous mettez PosgreSQL \`a jour, vous devez reconfigurer, recompiler et +r\'einstaller Bacula, faute de quoi vous constaterez probalement des +erreurs \'etranges. +Pour cela, il vous faut installer le RPM source, modifier le fichier bacula.spec +pour l'accorder \`a votre version de PostgreSQL, reconstruire le RPM et l'installer. + +If you upgrade PostgreSQL, you must reconfigure, rebuild, and re-install +Bacula otherwise you are likely to get bizarre failures. If you +to modify the bacula.spec file to account for the new PostgreSQL version. +You can do so by rebuilding from the source rpm. To do so, you may need +install from rpms and you upgrade PostgreSQL, you must also rebuild Bacula. + + +\section{Credits} +\index[general]{Credits } +\addcontentsline{toc}{section}{Credits} + +Tous mes remerciements \`a Dan Languille pour l'\'ecriture du driver +PostgreSQL qui deviendra tr\`es certainement la base de donn\'ees la plus +r\'eput\'ee utilisable avec {\bf Bacula} diff --git a/docs/manuals/fr/catalog/setup.sm b/docs/manuals/fr/catalog/setup.sm new file mode 100644 index 00000000..7c88dc61 --- /dev/null +++ b/docs/manuals/fr/catalog/setup.sm @@ -0,0 +1,23 @@ +/* + * html2latex + */ + +available { + sun4_sunos.4 + sun4_solaris.2 + rs_aix.3 + rs_aix.4 + sgi_irix +} + +description { + From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX +} + +install { + bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex + bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag + bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag + bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag + man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1 +} diff --git a/docs/manuals/fr/catalog/sqlite.tex b/docs/manuals/fr/catalog/sqlite.tex new file mode 100644 index 00000000..a5ef8790 --- /dev/null +++ b/docs/manuals/fr/catalog/sqlite.tex @@ -0,0 +1,168 @@ +%% +%% + +\chapter{Installing and Configuring SQLite} +\label{SqlLiteChapter} +\index[general]{Installing and Configuring SQLite } +\index[general]{SQLite!Installing and Configuring } + +Please note that SQLite both versions 2 and 3 are not network enabled, +which means that they must be linked into the Director rather than accessed +by the network as MySQL and PostgreSQL are. This has two consequences: +\begin{enumerate} +\item SQLite cannot be used in the {\bf bweb} web GUI package. +\item If you use SQLite, and your Storage daemon is not on the same +machine as your Director, you will need to transfer your database +to the Storage daemon's machine before you can use any of the SD tools +such as {\bf bscan}, ... +\end{enumerate} + +\section{Installing and Configuring SQLite -- Phase I} +\index[general]{Phase I!Installing and Configuring SQLite -- } +\index[general]{Installing and Configuring SQLite -- Phase I } + +If you use the {\bf ./configure \verb:--:with-sqlite} statement for configuring {\bf +Bacula}, you will need SQLite version 2.8.16 or later installed. Our standard +location (for the moment) for SQLite is in the dependency package {\bf +depkgs/sqlite-2.8.16}. Please note that the version will be updated as new +versions are available and tested. + +Installing and Configuring is quite easy. + +\begin{enumerate} +\item Download the Bacula dependency packages +\item Detar it with something like: + + {\bf tar xvfz depkgs.tar.gz} + + Note, the above command requires GNU tar. If you do not have GNU tar, a + command such as: + + {\bf zcat depkgs.tar.gz | tar xvf -} + + will probably accomplish the same thing. + +\item {\bf cd depkgs} + +\item {\bf make sqlite} + +\end{enumerate} + + +Please note that the {\bf ./configure} used to build {\bf Bacula} will need to +include {\bf \verb:--:with-sqlite} or {\bf \verb:--:with-sqlite3} depending +one which version of SQLite you are using. You should not use the {\bf +\verb:--:enable-batch-insert} configuration parameter for Bacula if you +are using SQLite version 2 as it is probably not thread safe. If you +are using SQLite version 3, you may use the {\bf \verb:--:enable-batch-insert} +configuration option with Bacula, but when building SQLite3 you MUST +configure it with {\bf \verb:--:enable-threadsafe} and +{\bf \verb:--:enable-cross-thread-connections}. + +By default, SQLite3 is now run with {\bf PRAGMA synchronous=OFF} this +increases the speed by more than 30 time, but it also increases the +possibility of a corrupted database if your server crashes (power failure +or kernel bug). If you want more security, you can change the PRAGMA +that is used in the file src/version.h. + + +At this point, you should return to completing the installation of {\bf +Bacula}. + + +\section{Installing and Configuring SQLite -- Phase II} +\label{phase2} +\index[general]{Phase II!Installing and Configuring SQLite -- } +\index[general]{Installing and Configuring SQLite -- Phase II } + +This phase is done {\bf after} you have run the {\bf ./configure} command to +configure {\bf Bacula}. + +{\bf Bacula} will install scripts for manipulating the database (create, +delete, make tables etc) into the main installation directory. These files +will be of the form *\_bacula\_* (e.g. create\_bacula\_database). These files +are also available in the \lt{}bacula-src\gt{}/src/cats directory after +running ./configure. If you inspect create\_bacula\_database, you will see +that it calls create\_sqlite\_database. The *\_bacula\_* files are provided +for convenience. It doesn't matter what database you have chosen; +create\_bacula\_database will always create your database. + +At this point, you can create the SQLite database and tables: + +\begin{enumerate} +\item cd \lt{}install-directory\gt{} + + This directory contains the Bacula catalog interface routines. + +\item ./make\_sqlite\_tables + + This script creates the SQLite database as well as the tables used by {\bf + Bacula}. This script will be automatically setup by the {\bf ./configure} + program to create a database named {\bf bacula.db} in {\bf Bacula's} working + directory. +\end{enumerate} + +\section{Linking Bacula with SQLite} +\index[general]{SQLite!Linking Bacula with } +\index[general]{Linking Bacula with SQLite } + +If you have followed the above steps, this will all happen automatically and +the SQLite libraries will be linked into {\bf Bacula}. + +\section{Testing SQLite} +\index[general]{SQLite!Testing } +\index[general]{Testing SQLite } + +We have much less "production" experience using SQLite than using MySQL. +SQLite has performed flawlessly for us in all our testing. However, +several users have reported corrupted databases while using SQLite. For +that reason, we do not recommend it for production use. + +If Bacula crashes with the following type of error when it is started: +\footnotesize +\begin{verbatim} +Using default Catalog name=MyCatalog DB=bacula +Could not open database "bacula". +sqlite.c:151 Unable to open Database=/var/lib/bacula/bacula.db. +ERR=malformed database schema - unable to open a temporary database file +for storing temporary tables +\end{verbatim} +\normalsize + +this is most likely caused by the fact that some versions of +SQLite attempt to create a temporary file in the current directory. +If that fails, because Bacula does not have write permission on +the current directory, then you may get this errr. The solution is +to start Bacula in a current directory where it has write permission. + + +\section{Re-initializing the Catalog Database} +\index[general]{Database!Re-initializing the Catalog } +\index[general]{Re-initializing the Catalog Database } + +After you have done some initial testing with {\bf Bacula}, you will probably +want to re-initialize the catalog database and throw away all the test Jobs +that you ran. To do so, you can do the following: + +\footnotesize +\begin{verbatim} + cd + ./drop_sqlite_tables + ./make_sqlite_tables +\end{verbatim} +\normalsize + +Please note that all information in the database will be lost and you will be +starting from scratch. If you have written on any Volumes, you must write an +end of file mark on the volume so that Bacula can reuse it. Do so with: + +\footnotesize +\begin{verbatim} + (stop Bacula or unmount the drive) + mt -f /dev/nst0 rewind + mt -f /dev/nst0 weof +\end{verbatim} +\normalsize + +Where you should replace {\bf /dev/nst0} with the appropriate tape drive +device name for your machine. diff --git a/docs/manuals/fr/catalog/translate_images.pl b/docs/manuals/fr/catalog/translate_images.pl new file mode 100755 index 00000000..c7225118 --- /dev/null +++ b/docs/manuals/fr/catalog/translate_images.pl @@ -0,0 +1,185 @@ +#!/usr/bin/perl -w +# +use strict; + +# Used to change the names of the image files generated by latex2html from imgxx.png +# to meaningful names. Provision is made to go either from or to the meaningful names. +# The meaningful names are obtained from a file called imagename_translations, which +# is generated by extensions to latex2html in the make_image_file subroutine in +# bacula.perl. + +# Opens the file imagename_translations and reads the contents into a hash. +# The hash is creaed with the imgxx.png files as the key if processing TO +# meaningful filenames, and with the meaningful filenames as the key if +# processing FROM meaningful filenames. +# Then opens the html file(s) indicated in the command-line arguments and +# changes all image references according to the translations described in the +# above file. Finally, it renames the image files. +# +# Original creation: 3-27-05 by Karl Cunningham. +# Modified 5-21-05 to go FROM and TO meaningful filenames. +# +my $TRANSFILE = "imagename_translations"; +my $path; + +# Loads the contents of $TRANSFILE file into the hash referenced in the first +# argument. The hash is loaded to translate old to new if $direction is 0, +# otherwise it is loaded to translate new to old. In this context, the +# 'old' filename is the meaningful name, and the 'new' filename is the +# imgxx.png filename. It is assumed that the old image is the one that +# latex2html has used as the source to create the imgxx.png filename. +# The filename extension is taken from the file +sub read_transfile { + my ($trans,$direction) = @_; + + if (!open IN,"<$path$TRANSFILE") { + print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n"; + print " Image filename translation aborted\n\n"; + exit 0; + } + + while () { + chomp; + my ($new,$old) = split(/\001/); + + # Old filenames will usually have a leading ./ which we don't need. + $old =~ s/^\.\///; + + # The filename extension of the old filename must be made to match + # the new filename because it indicates the encoding format of the image. + my ($ext) = $new =~ /(\.[^\.]*)$/; + $old =~ s/\.[^\.]*$/$ext/; + if ($direction == 0) { + $trans->{$new} = $old; + } else { + $trans->{$old} = $new; + } + } + close IN; +} + +# Translates the image names in the file given as the first argument, according to +# the translations in the hash that is given as the second argument. +# The file contents are read in entirely into a string, the string is processed, and +# the file contents are then written. No particular care is taken to ensure that the +# file is not lost if a system failure occurs at an inopportune time. It is assumed +# that the html files being processed here can be recreated on demand. +# +# Links to other files are added to the %filelist for processing. That way, +# all linked files will be processed (assuming they are local). +sub translate_html { + my ($filename,$trans,$filelist) = @_; + my ($contents,$out,$this,$img,$dest); + my $cnt = 0; + + # If the filename is an external link ignore it. And drop any file:// from + # the filename. + $filename =~ /^(http|ftp|mailto)\:/ and return 0; + $filename =~ s/^file\:\/\///; + # Load the contents of the html file. + if (!open IF,"<$path$filename") { + print "WARNING: Cannot open $path$filename for reading\n"; + print " Image Filename Translation aborted\n\n"; + exit 0; + } + + while () { + $contents .= $_; + } + close IF; + + # Now do the translation... + # First, search for an image filename. + while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) { + $contents = $'; + $out .= $` . $&; + + # The next thing is an image name. Get it and translate it. + $contents =~ /^(.*?)\"/s; + $contents = $'; + $this = $&; + $img = $1; + # If the image is in our list of ones to be translated, do it + # and feed the result to the output. + $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img})); + $out .= $this; + } + $out .= $contents; + + # Now send the translated text to the html file, overwriting what's there. + open OF,">$path$filename" or die "Cannot open $path$filename for writing\n"; + print OF $out; + close OF; + + # Now look for any links to other files and add them to the list of files to do. + while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) { + $out = $'; + $dest = $1; + # Drop an # and anything after it. + $dest =~ s/\#.*//; + $filelist->{$dest} = '' if $dest; + } + return $cnt; +} + +# REnames the image files spefified in the %translate hash. +sub rename_images { + my $translate = shift; + my ($response); + + foreach (keys(%$translate)) { + if (! $translate->{$_}) { + print " WARNING: No destination Filename for $_\n"; + } else { + $response = `mv -f $path$_ $path$translate->{$_} 2>&1`; + $response and print "ERROR from system $response\n"; + } + } +} + +################################################# +############# MAIN ############################# +################################################ + +# %filelist starts out with keys from the @ARGV list. As files are processed, +# any links to other files are added to the %filelist. A hash of processed +# files is kept so we don't do any twice. + +# The first argument must be either --to_meaningful_names or --from_meaningful_names + +my (%translate,$search_regex,%filelist,%completed,$thisfile); +my ($cnt,$direction); + +my $arg0 = shift(@ARGV); +$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or + die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n"; + +$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1; + +(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n"; + +# Use the first argument to get the path to the file of translations. +my $tmp = $ARGV[0]; +($path) = $tmp =~ /(.*\/)/; +$path = '' unless $path; + +read_transfile(\%translate,$direction); + +foreach (@ARGV) { + # Strip the path from the filename, and use it later on. + if (s/(.*\/)//) { + $path = $1; + } else { + $path = ''; + } + $filelist{$_} = ''; + + while ($thisfile = (keys(%filelist))[0]) { + $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile})); + delete($filelist{$thisfile}); + $completed{$thisfile} = ''; + } + print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n"; +} + +rename_images(\%translate); diff --git a/docs/manuals/fr/catalog/update_version b/docs/manuals/fr/catalog/update_version new file mode 100755 index 00000000..5c2e0092 --- /dev/null +++ b/docs/manuals/fr/catalog/update_version @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/catalog/update_version.in b/docs/manuals/fr/catalog/update_version.in new file mode 100644 index 00000000..2766245f --- /dev/null +++ b/docs/manuals/fr/catalog/update_version.in @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/catalog/version.tex b/docs/manuals/fr/catalog/version.tex new file mode 100644 index 00000000..82d910aa --- /dev/null +++ b/docs/manuals/fr/catalog/version.tex @@ -0,0 +1 @@ +2.3.6 (04 November 2007) diff --git a/docs/manuals/fr/catalog/version.tex.in b/docs/manuals/fr/catalog/version.tex.in new file mode 100644 index 00000000..ff66dfc6 --- /dev/null +++ b/docs/manuals/fr/catalog/version.tex.in @@ -0,0 +1 @@ +@VERSION@ (@DATE@) diff --git a/docs/manuals/fr/concepts/Makefile b/docs/manuals/fr/concepts/Makefile new file mode 100644 index 00000000..61b86ed0 --- /dev/null +++ b/docs/manuals/fr/concepts/Makefile @@ -0,0 +1,139 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=concepts + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null + makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null + makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null + makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Concepts and Overview Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Concep_Overvi_Guide.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/concepts/Makefile.in b/docs/manuals/fr/concepts/Makefile.in new file mode 100644 index 00000000..61b86ed0 --- /dev/null +++ b/docs/manuals/fr/concepts/Makefile.in @@ -0,0 +1,139 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=concepts + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null + makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null + makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null + makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Concepts and Overview Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Concep_Overvi_Guide.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/concepts/STYLE b/docs/manuals/fr/concepts/STYLE new file mode 100644 index 00000000..6cd70564 --- /dev/null +++ b/docs/manuals/fr/concepts/STYLE @@ -0,0 +1,76 @@ +TODO + +maybe spell out "config" to "configuration" as appropriate + +Use American versus British spelling + +not critical, but for later consider cleaning out some use of +"there" and rewrite to not be so passive. + +make sure use of \elink shows URL in printed book + +get rid of many references of "Red Hat" -- too platform specific? + +remove references to names, like "Dan Langille shared ..." +just put their names in credits for book + +don't refer to very old software by specific version such as +"Red Hat 7" or FreeBSD 4.9 because is too old to put in book. It may be +relevant, but may be confusing. Maybe just remove the version number +if applicable. + +maybe fine, but discuss point-of-view: don't use personal "I" or +possessive "my" unless that is consistent style for book. + +replace "32 bit" and "64 bit" with "32-bit" and "64-bit" respectively. +It seems like more popular style standard + +be consistent with "Note" and "NOTE". maybe use tex header for this + +get rid of redundant or noisy exclamation marks + +style for "ctl-alt-del" and "ctl-d"? and be consisten with formatting + +be consistent for case for ext3, ext2, EXT3, or EXT2. + +fix spelling of "inspite" in source and in docs (maybe use "regardless +in one place where I already changed to "in spite" + +be consistent with software names, like postgres, postgresql, PostreSQL +and others + +instead of using whitehouse for examples, use example.org (as that is defined +for that usage); also check other hostnames and maybe IPs and networks + +use section numbers and cross reference by section number or page number +no underlining in book (this is not the web :) + +some big gaps between paragraphs or between section headers and paragraphs +-- due to tex -- adjust as necessary to look nice + +don't include the GPL and LGPL in book. This will save 19 (A4) pages. +For 6x9 book this will save 30 pages. (Keep GFDL though.) + +many index items are too long + +appendices not listed as appendix + +some how consolidate indexes into one? on 6x9, the indexes are over 30 pages + +don't refer to some website without including URL also +(such as "this FreeBSD Diary article") + +get rid of (R) trademark symbols -- only use on first use; for example +don't put on the RPM Packaging FAQ + +split up very long paragraphs, such as "As mentioned above, you will need ..." +(on my page 783). + +use smaller font or split up long lines (especially from +console output which is wider than printed page) + +don't assume all BSD is "FreeBSD" + +don't assume all "kernel" is Linux. If it is Linux, be clear. + + diff --git a/docs/manuals/fr/concepts/ansi-labels.tex b/docs/manuals/fr/concepts/ansi-labels.tex new file mode 100644 index 00000000..7d6e14fe --- /dev/null +++ b/docs/manuals/fr/concepts/ansi-labels.tex @@ -0,0 +1,58 @@ + +\chapter{ANSI and IBM Tape Labels} +\label{AnsiLabelsChapter} +\index[general]{ANSI and IBM Tape Labels} +\index[general]{Labels!Tape} + +Bacula supports ANSI or IBM tape labels as long as you +enable it. In fact, with the proper configuration, you can +force Bacula to require ANSI or IBM labels. + +Bacula can create an ANSI or IBM label, but if Check Labels is +enabled (see below), Bacula will look for an existing label, and +if it is found, it will keep the label. Consequently, you +can label the tapes with programs other than Bacula, and Bacula +will recognize and support them. + +Even though Bacula will recognize and write ANSI and IBM labels, +it always writes its own tape labels as well. + +When using ANSI or IBM tape labeling, you must restrict your Volume +names to a maximum of six characters. + +If you have labeled your Volumes outside of Bacula, then the +ANSI/IBM label will be recognized by Bacula only if you have created +the HDR1 label with {\bf BACULA.DATA} in the Filename field (starting +with character 5). If Bacula writes the labels, it will use +this information to recognize the tape as a Bacula tape. This allows +ANSI/IBM labeled tapes to be used at sites with multiple machines +and multiple backup programs. + + +\section{Director Pool Directive} + +\begin{description} +\item [ Label Type = ANSI | IBM | Bacula] + This directive is implemented in the Director Pool resource and in the SD Device + resource. If it is specified in the SD Device resource, it will take + precedence over the value passed from the Director to the SD. The default + is Label Type = Bacula. +\end{description} + +\section{Storage Daemon Device Directives} + +\begin{description} +\item [ Label Type = ANSI | IBM | Bacula] + This directive is implemented in the Director Pool resource and in the SD Device + resource. If it is specified in the the SD Device resource, it will take + precedence over the value passed from the Director to the SD. + +\item [Check Labels = yes | no] + This directive is implemented in the the SD Device resource. If you intend + to read ANSI or IBM labels, this *must* be set. Even if the volume is + not ANSI labeled, you can set this to yes, and Bacula will check the + label type. Without this directive set to yes, Bacula will assume that + labels are of Bacula type and will not check for ANSI or IBM labels. + In other words, if there is a possibility of Bacula encountering an + ANSI/IBM label, you must set this to yes. +\end{description} diff --git a/docs/manuals/fr/concepts/autochangerres.tex b/docs/manuals/fr/concepts/autochangerres.tex new file mode 100644 index 00000000..048d20c5 --- /dev/null +++ b/docs/manuals/fr/concepts/autochangerres.tex @@ -0,0 +1,109 @@ +\chapter{La ressource Autochanger} +\label{Autochangerres} +\index[sd]{Autochanger Ressource } +\index[sd]{Ressource!Autochanger } + +La ressource Autochanger supporte les librairies \`a un ou plusieurs +lecteurs en regroupant une ou plusieurs ressources Device en une +unit\'e nomm\'ee Autochanger dans Bacula (souvent d\'esign\'ee en tant que +librairie de bandes par les constructeurs). Si vous poss\'edez une +librairie, et si vous voulez qu'elle fonctionne correctement, vous +{\bf devez} avoir une ressource Autochanger dans le fichier de +configuration de votre Storage Daemon, et les directives Storage +de votre Director {\bf doivent} se r\'ef\'erer au nom de la ressource +Autochanger si elles sont suppos\'ees utiliser la librairie. Dans les +versions ant\'erieures \`a 1.38.0, les directives Storage du Director +se r\'ef\'eraient directement aux ressources Device qui \'etaient des +librairies. D\'esormais, ce type de r\'ef\'erence directe ne fonctionne +plus avec les librairies. + +\begin{description} +\item [Name = \lt{}Autochanger-Name\gt{}] + \index[sd]{Name} + Sp\'ecifie le nom de la librairie. Ce nom est utilis\'e dans la + la d\'efinition de ressource Storage du Director afin de d\'esigner + la librairie. Cette directive est requise. + +\item [Device = \lt{}Device-name1, device-name2, ...\gt{}] + Sp\'ecifie le nom de la (ou des) ressource(s) Device associ\'ees \`a la + librairie. Si votre librairie contient plusieurs lecteurs, vous + devez sp\'ecifier plusieurs noms de ressources Device, chacun d\'esignant + une ressource Device distincte qui comporte un + Drive Index correspondant au num\'ero de lecteur. Vous pouvez sp\'ecifier + plusieurs noms en une seule ligne s\'epar\'es par des virgules ou/et utiliser + plusieurs fois la directive Device. Cette directive est requise. + +\item [Changer Device = {\it name-string}] + \index[sd]{Changer Device} + La cha\^ine {\bf name-string} sp\'ecifi\'ee indique le nom du fichier syst\`eme + d\'esignant la librairie. S'il est sp\'ecifi\'e dans cette ressource, ce nom + n'est pas requis dans la ressource Device. Le nom \'eventuellement sp\'ecifi\'e + dans la ressource Device prend le pas sur celui sp\'ecifi\'e dans la ressource + Autochanger. + +\item [Changer Command = {\it name-string}] + \index[sd]{Changer Command } + La cha\^ine {\bf name-string} sp\'ecifie un programme externe appel\'e pour + changer de volume automatiquement \`a la demande de Bacula. La plupart du + temps, vous renseignerez ce champ avec le script fourni {\bf mtx-changer} + comme suit. Si cette commande est sp\'ecifi\'ee ici, elle n'a pas besoin de + l'\^etre dans la ressource Device. Dans le cas o\`u elle le serait dans les deux + ressources, la sp\'ecification de la ressource Device prendrait le pas sur celle + de la ressource Autochanger. + +\end{description} + +Voici un exemple de d\'efinition de ressource Autochanger valide : + +\footnotesize +\begin{verbatim} +Autochanger { + Name = "DDS-4-changer" + Device = DDS-4-1, DDS-4-2, DDS-4-3 + Changer Device = /dev/sg0 + Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d" +} +Device { + Name = "DDS-4-1" + Drive Index = 0 + Autochanger = yes + ... +} +Device { + Name = "DDS-4-2" + Drive Index = 1 + Autochanger = yes + ... +Device { + Name = "DDS-4-3" + Drive Index = 2 + Autochanger = yes + Autoselect = no + ... +} +\end{verbatim} +\normalsize + +Notez l'importance de la directive {\bf Autochanger = yes} dans chaque d\'efinition +de p\'eriph\'erique appartenant \`a une librairie. Un p\'eriph\'erique ne devrait pas \^etre +d\'efini comme appartenant \`a plusieurs librairies. Aussi, votre directive Device +dans la ressource Storage du Director devrait comporter le nom de la ressource +Autochanger plut\^ot que le nom de l'un des lecteurs. + +Si vous avez un lecteur qui appartient physiquement \`a une librairie mais que +vous ne souhaitez pas que Bacula puisse l'utiliser automatiquement (par exemple, +si vous voulez le r\'eserver pour les restaurations) vous pouvez utiliser la +directive : + +\footnotesize +\begin{verbatim} +Autoselect = no +\end{verbatim} +\normalsize + +\`a la ressource Device de ce lecteur. Dans ce cas, Bacula ne le s\'electionnera pas +automatiquement en acc\'edant \`a la librairie. Vous pouvez encore utiliser le lecteur en +le d\'esignant par son nom de ressource device plut\^ot que par celui de la ressource +Autochanger. Un exemple d'une telle d\'efinition est montr\'e ci-dessus pour le +lecteur DDS-4-3, qui ne sera pas s\'electionn\'e si le nom DDS-4-changer est utilis\'e +dans une ressource Storage, mais le sera si DDS-4-3 est utilis\'e. diff --git a/docs/manuals/fr/concepts/autochangers.tex b/docs/manuals/fr/concepts/autochangers.tex new file mode 100644 index 00000000..78c5f126 --- /dev/null +++ b/docs/manuals/fr/concepts/autochangers.tex @@ -0,0 +1,936 @@ +%% +%% + +\chapter{Support des librairies} +\label{AutochangersChapter} +\index[general]{Support!Librairies} +\index[general]{Autochanger Support } +\addcontentsline{toc}{section}{Support des librairies} + +Bacula supporte les librairies pour les op\'erations de lecture et \'ecriture. +Plusieurs conditions sont requises pour que Bacula puisse utiliser une librairie. +Celles-ci sont expliqu\'ees en d\'etail ci-dessous. +Mais voyons d'abord la liste de ces conditions : + +\begin{itemize} +\item Un script charg\'e de piloter la librairie en accord avec les commandes + envoy\'ees par Bacula est requis. Nous fournissons un tel script pr\'evu pour fonctionner + avec le programme {\bf mtx} disponible dans les paquets {\bf depkgs}. ce script ne + fonctionne qu'avec les librairies \`a un seul lecteur. +\item Chaque volume \`a utiliser doit \^etre d\'efini dans le catalogue et avoir + un num\'ero de slot (NDT : emplacement dans la librairie) assign\'e, de sorte + que Bacula puisse savoir o\`u se trouve le volume dans la librairie. Cet + enregistrement se fait la plupart du temps gr\^ace \`a la commande {\bf label}. + Voyez ci-dessous pour plus de d\'etails. Vous devez \'etiqueter manuellement + vos cartouches avant de pouvoir les utiliser. +\item Vous devez avoir modifi\'e le fichier de configuration de votre Storage + Daemon afin que la ressource Device identifie votre p\'eriph\'erique en tant + que librairie. Quelques autres param\`etres doivent \^etre d\'efinis. +\item Vous devriez aussi modifier la d\'efinition de ressource Storage dans le +fichier de configuration du Director en sorte que le slot vous soit automatiquement +demand\'e lorque vous \'etiquetez un volume. +\item Si vous n'ex\'ecutez pas le Storage Daemon en tant que root, vous devez + vous assurer qu'il d\'etient les droits requis pour acc\'eder au lecteur et au + bras robotis\'e de la librairie. +\item Vous devez placer la directive {\bf Autochanger = yes} dans la + ressource Storage de votre fichier bacula-dir.conf, de sorte que vous soyez + interrog\'e au sujet du slot \`a chaque \'etiquetage de cartouche. +\end{itemize} + +Dans les versions ult\'erieures \`a 1.37, la nouvelle directive +\ilink{Autochanger resource}{AutochangerRes} permet de grouper les ressources +Device pour cr\'eer des librairies avec plusieurs lecteurs. Si vous avez une +librairie, vous devez utiliser cette ressource. + +Bacula utilise son propre script {\bf mtx-changer} pour interagir avec un +programme qui effectue r\'eellement les changement de cartouches. Ainsi, +{\bf mtx-changer} peut \^etre adapt\'e pour fonctionner avec n'importe quel +programme de prise en chgarge de librairie. La version actuelle de +{\bf mtx-changer} fonctionne avec le programme {\bf mtx} . Cependant, +des utilisateurs de FreeBSD ont r\'ealis\'e un script, disponible dans +le r\'epertoire {\bf examples/autochangers}, qui permet \`a Bacula de fonctionner +avec le programme {\bf chio}. + +Bacula supporte aussi les librairies \'equip\'ees de lecteurs de codes barres. +Ce support inclut deux commandes de la console Bacula : {\bf label barcodes} +et {\bf update slots}. Pour plus de d\'etails au sujet de ces commandes, +voyez la section "Support des lecteurs de codes barres" plus loin. + +Le support des librairies dans Bacula n'inclue pas, pour le moment, la gestion +du nettoyage des lecteurs, ni celle des bacs de cartouches ou des silos. + +Le support des librairies \`a un ou plusieurs lecteurs requiert la ressource +\ilink{Autochanger resource}{AutochangerRes}. + +En principe, si {\bf mtx} fonctionne correctement avec votre librairie, ce +n'est qu'une question d'adaptation du script {\bf mtx-changer} pour que +Bacula s'interface correctement avec la librairie. Vous pouvez trouver une +liste des librairies support\'ees par {\bf mtx} en suivant le lien suivant : +\elink{http://mtx.opensource-sw.net/compatibility.php} +{http://mtx.opensource-sw.net/compatibility.php}. +Le site officiel du projet {\bf mtx} se trouve ici : +\elink{http://mtx.opensource-sw.net/}{http://mtx.opensource-sw.net/}. + +Si vous avez des difficult\'es, veuillez utiliser la commande {\bf auto} du +programme {\bf btape} pour tester le fonctionnement de votre librairie +avec Bacula. Lorsque Bacula fonctionne, souvenez vous que pour beaucoup de +distributions (par exemple FreeBSD, Debian,...), le Storage Daemon est +ex\'ecut\'e en tant que {\bf bacula.tape} plut\^ot que {\bf root.root}, aussi +vous devrez vous assurer que le Storage Daemon dispose de droits suffisants pour +acc\'eder \`a la librairie. + +\label{SCSI devices} +\section*{D\'eterminer vos p\'eriph\'eriques SCSI} +\index[general]{D\'eterminer!p\'eriph\'eriques SCSI} +\index[general]{D\'eterminer vos p\'eriph\'eriques SCSI} +\index[general]{P\'eriph\'eriques} +\index[general]{p\'eriph\'eriques!SCSI} + +Sous Linux, vous pouvez lire le fichier /proc/scsi/scsi : + +\footnotesize +\begin{verbatim} +cat /proc/scsi/scsi +\end{verbatim} +\normalsize + +pour conna\^itre vos p\'eriph\'eriques SCSI. Vous pouvez aussi examiner les fichiers +/proc/scsi/sg/device\_hdr et /proc/scsi/sg/devices : + +footnotesize +\begin{verbatim} +cat /proc/scsi/sg/device_hdr /proc/scsi/sg/devices +\end{verbatim} +\normalsize + +pour d\'eterminer comment sp\'ecifier leur nom de p\'eriph\'erique ({\bf /dev/sg0} +pour le premier, {\bf /dev/sg1} pour le second, ...) au niveau de +la directive {\bf Changer Device} + +Pour des informations plus d\'etaill\'ees sur le sujet, veuillez consulter la +section \ilink{Linux SCSI Tricks}{SCSITricks} du chapitre sur les tests +de lecteurs de ce manuel. + +Sous FreeBSD, vous disposez de la commande : + +\footnotesize +\begin{verbatim} +camcontrol devlist +\end{verbatim} +\normalsize + +pour afficher la liste des p\'eriph\'eriques SCSI ainsi que le {\bf /dev/passn} +que vous utiliserez pour renseigner la directive {\bf Changer Device} + +Assurez-vous que votre Storage Daemon dispose bien des privil\`eges requis +pour acc\'eder \`a ce p\'eriph\'erique. + +L'astuce suivante, destin\'ee aux utilisateurs de FreeBSD, provient de +Danny Butroyd. Au red\'emarrage, Bacula n'aura PLUS les permissions +requises pour contr\^oler le p\'eriph\'erique /dev/pass0. Pour vous +affanchir de cette difficult\'e, \'editez le fichier /etc/devfs.conf et +ajoutez lui ceci : + +\footnotesize +\begin{verbatim} +own pass0 root:bacula +perm pass0 0666 +own nsa0.0 root:bacula +perm nsa0.0 0666 +\end{verbatim} +\normalsize + +Nous avons ainsi donn\'e au groupe Bacula la permission d'\'ecrire +sur le p\'eriph\'erique nsa0.0. Pour activer ces modifications, ex\'ecutez : +/etc/rc.d/devfs restart + +Vous n'aurez plus \`a modifier les permissions sur ces p\'eriph\'eriques +pour que Bacula continue d'utiliser la librairie apr\`es un red\'emarrage. + +\label{scripts} + +\section{Exemples de scripts} +\index[general]{Scripts!Exemples } +\index[general]{Exemples de scripts } + +Veuillez lire les sections ci-dessous pour bien comprendre comment +les librairies fonctionnent avec Bacula. Bien que nous fournissions +un script {\bf mtx-changer} par d\'efaut, il se peut que votre librairie +n\'ecessite quelques am\'enagements de ce script. Si vous voulez voir des +exemples de fichiers de configuration et de scripts, jetez un oeil +au r\'epertoire \lt{}bacula-src\gt{}/examples/devices o\`u vous +trouverez un exemple de ressource Device Bacula : {\bf HP-autoloader.conf} +ainsi que plusieurs scripts {\bf mtx-changer} modifi\'es pour fonctionner +avec diverses librairies. + +\label{Slots} + +\section*{Slots} +\index[general]{Slots } + +Pour utiliser convenablement une librairie, Bacula doit savoir quel volume +se trouve dans quel {\bf slot} de la librairie. Les slots sont les +emplacements o\`u sont rang\'ees les cartouches lorsqu'elles ne sont pas dans un +lecteur. Bacula num\'erote ces slots de un jusqu'au nombre de cartouches +contenues dans la librairie. + +Bacula n'utilisera pas automatiquement une cartouche pr\'esente dans la librairie +si elle ne porte pas d'\'etiquette (label) Bacula et si son num\'ero de slot n'est pas +r\'ef\'erenc\'e dans le catalogue. Vous devez, \`a l'aide de la console, assigner un +slot \`a chaque cartouche pr\'esente dans la librairie. Cette information est +conserv\'ee dans le catalogue avec les autres donn\'ees relatives au volume. +Si le slot n'est pas pr\'ecis\'e, ou s'il est \'egal \`a z\'ero, alors Bacula ne tentera +pas d'utiliser la librairie, m\^eme si tous les enregistrements de configuration +sont pr\'esents. De m\^eme, la commande {\bf mount} de la console Bacula ne +provoque pas non plus l'utilisation de la librairie, mais se contente d'ordonner +\`a Bacula de lire toute cartouche \'eventuellement pr\'esente dans le lecteur. + +Vous pouvez contr\^oler le num\'ero de slot et le drapeau InChanger avec la commande : + +\begin{verbatim} +list Volumes +\end{verbatim} + +dans la console. + +\label{mult} +\section*{Lecteurs multiples} +\index[general]{Lecteurs!Multiples } +\index[general]{Lecteurs ultiples} + +Certaines librairies comportent plusieurs p\'eriph\'eriques de lecture/\'ectriture +(lecteurs). La nouvelle \ilink{ressource Autochanger}{AutochangerRes} +apparue avec la version 1.37 vous permet de grouper des ressources Devices +(repr\'esentant chacune un lecteur). Le Director est toujours en mesure +d'adresser directement un lecteur, mais ce faisant, il outrepasse +le fonctionnement propre aux groupements de lecteurs. Il est pr\'ef\'erable +que la Ressource Storage du Director d\'efinisse une ressource +Autochanger, permettant ainsi au Storage Daemon de s'assurer qu'un seul +lecteur \`a la fois utilise le script mtx-changer, et que deux lecteurs ne tentent +pas de lire le m\^eme volume. + +Les librairies \`a lecteurs multiples n\'ecessitent d'utiliser la directive +{\bf Drive Index} dans la ressource Device du Storage Daemon. Les +lecteurs sont num\'erot\'es \`a partir de z\'ero, ce qui constitue la valeur par +d\'efaut. Pour utiliser un deuxi\`eme lecteur dans une librairie, vous devez +d\'efinir une seconde ressource Device et lui attribuer le Drive Index 1. +En g\'en\'eral, le second p\'eriph\'erique aura le m\^eme {\bf Changer Device} +(canal de contr\^ole) que le premier, mais une {\bf Archive Device} diff\'erente. + +Par d\'efaut, les jobs Bacula pr\'ef\`erent \'ecrire sur un volume d\'ej\`a mont\'e. +Si vous avez une librairie avec plusieurs lecteurs, et si vous souhaitez que +Bacula \'ecrive sur plusieurs volumes du m\^eme pool en m\^eme temps, vous devez +d\'esactiver la directive \ilink{Prefer Mounted Volumes} {PreferMountedVolumes} +dans la ressource Job du Director. Ainsi le Storage Daemon pourra maximiser +l'usage des lecteurs. + +\label{ConfigRecords} +\subsection*{Directives de la ressource Device} +\index[general]{Directives!ressource Device} +\index[general]{Directives de la ressource Device} + +La configuration des librairies s'effectue dans Bacula au niveau de le ressource +Device du Storage Daemon. Quatre directives permettent de d\'efinir l'usage de +la librairie par Bacula : {\bf Autochanger}, {\bf Changer Device}, +{\bf Changer Command} et {\bf Maximum Changer Wait} + +Ces quatre directives sont d\'ecrites en d\'etail ci-dessous. Notez cependant +que les directives {\bf Changer Device} et {\bf Changer Command} ne sont pas +requises dans la ressource Device si elles figurent dans la ressource +{\bf Autochanger}. + +\begin{description} + +\item [Autochanger = {\it Yes|No} ] + \index[sd]{Autochanger} + La directive {\bf Autochanger} stipule que le p\'eriph\'erique ainsi d\'efini est, ou + n'est pas, une librairie. La valeur par d\'efaut est {\bf no}. + +\item [Changer Device = \lt{}device-name\gt{}] + \index[sd]{Changer Device} + En plus du nom d'Archive Device, vous devez sp\'ecifier un nom de + librairie {\bf Changer Device}, ceci parce que la plupart des librairies + sont control\'ees via un pseudo-fichier diff\'erent de celui utilis\'e pour + lire et \'ecrire sur les cartouches. Par exemple, sur les syst\`emes Linux, + on utilise g\'en\'eralement l'interface SCSI g\'en\'erique pour contr\^oler le bras + de la librairie, soit {\bf Changer Device = /dev/sg0} et l'interface SCSI + standard pour lire et \'ecrire sur les bandes, soit {\bf Archive Device = /dev/nst0}. + Notez que certaines librairies \'evolu\'ees localiseront le bras sur + {\bf /dev/sg1}. De telles librairies ont souvent plusieurs lecteurs et un + nombre important de cartouches. + + Sur FreeBSD, on sp\'ecifiera typiquement {\bf Changer Device = /dev/pass0} ou + {\bf Changer Device = /dev/passn}. + + Sur Solaris, ce sera {\bf Changer Device = /dev/rdsk}. + + Assurez vous que votre Storage Daemon poss\`ede les permissions d'acc\'eder \`a + ce p\'eriph\'erique. + +\item [Changer Command = \lt{}command\gt{}] + \index[sd]{Changer Command } + Cette directive est utilis\'ee pour sp\'ecifier le programme externe \`a appeler + et les arguments \`a lui fournir. La commande est suppos\'ee \^etre un programme + ou un script shell standard qui peut \^etre ex\'ecut\'e par le syst\`eme. cette + commande est invoqu\'ee chaque fois que Bacula manipule le bras de la librairie. + Les substitutions suivantes sont effectu\'ees dans la ligne {\bf command} + avant qu'elle ne soit envoy\'ee au syst\`eme d'exploitation pour ex\'ecution. + +\footnotesize +\begin{verbatim} + %% = % + %a = archive device name + %c = changer device name + %d = changer drive index base 0 + %f = Client's name + %j = Job name + %o = command (loaded, load, or unload) + %s = Slot base 0 + %S = Slot base 1 + %v = Volume name +\end{verbatim} +\normalsize + +Voici un exemple d'utilisation de {\bf mtx} avec le script {\bf mtx-changer} : + +\footnotesize +\begin{verbatim} +Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d" +\end{verbatim} +\normalsize + +O\`u vous devrez adapter le chemin {\bf /etc/bacula} pour qu'il co\''incide \`a +la r\'ealit\'e de votre installation. Les d\'etails des trois commandes (loaded, +load, unload) utilis\'ees par Bacula ainsi que la sortie qui en est attendue +sont donn\'es dans la section {\bf Interface entre Bacula et les librairies} +ci-dessous. + +\item [Maximum Changer Wait = \lt{}time\gt{}] + \index[sd]{Maximum Changer Wait} + Cette directive sert \`a d\'efinir le d\'elai maximal durant lequel Bacula + attendra la r\'eponse d'une librairie \`a une commande (par exemple, load). + La valeur par d\'efaut est 120 secondes. Si votre librairie est lente, vous + pouvez avoir int\'er\^et \`a allonger ce d\'elai. + + Au del\`a de ce d\'elai, le programme de chargement est tu\'e et Bacula + sollicite l'intervention d'un op\'erateur. + +\item [Drive Index = \lt{}number\gt{}] + \index[sd]{Drive Index} + Cette directive vous permet d'indiquer \`a Bacula d'utiliser le second + lecteur et les \'eventuels suivants dans une librairie qui en contient + plusieurs. Etant donn\'e que les lecteurs sont num\'erot\'es \`a partir de + z\'ero, le second est d\'efini par : + +\footnotesize +\begin{verbatim} +Device Index = 1 +\end{verbatim} +\normalsize + +Pour utiliser le second lecteur, vous devez avoir une seconde d\'efinition +de ressource Device dans le fichier bacula-sd.conf. Voyez la section +concernant les lecteurs multiples plus haut dans ce chapitre pour plus +de plus amples informations. +\end{description} + +De plus, pour un fonctionnement correct de la librairie, vous devez d\'efinir +une ressource Autochanger. +\input{autochangerres} + +\label{example} +\section{Un exemple de fichier de configuration} +\index[general]{exemple fichier configuration} +\index[general]{fichier!exemple configuration} + +Les deux ressource suivantes impl\'ementent une librairie : + +\footnotesize +\begin{verbatim} +Autochanger { + Name = "Autochanger" + Device = DDS-4 + Changer Device = /dev/sg0 + Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d" +} + +Device { + Name = DDS-4 + Media Type = DDS-4 + Archive Device = /dev/nst0 # Normal archive device + Autochanger = yes + LabelMedia = no; + AutomaticMount = yes; + AlwaysOpen = yes; +} +\end{verbatim} +\normalsize + +o\`u vous adapterez les directives {\bf Archive Device}, {\bf Changer Device} et +{\bf Changer Command} pour qu'elles conviennent \`a votre syst\`eme. + +\section{Un exemple de fichier de configuration multi-lecteurs} +\index[general]{Multi-lecteurs exemple fichier de configuration} + +Les ressources suivantes impl\'ementent une librairie multi-lecteurs : + +\footnotesize +\begin{verbatim} +Autochanger { + Name = "Autochanger" + Device = Drive-1, Drive-2 + Changer Device = /dev/sg0 + Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d" +} + +Device { + Name = Drive-1 + Drive Index = 0 + Media Type = DDS-4 + Archive Device = /dev/nst0 # Normal archive device + Autochanger = yes + LabelMedia = no; + AutomaticMount = yes; + AlwaysOpen = yes; +} + +Device { + Name = Drive-2 + Drive Index = 1 + Media Type = DDS-4 + Archive Device = /dev/nst1 # Normal archive device + Autochanger = yes + LabelMedia = no; + AutomaticMount = yes; + AlwaysOpen = yes; +} + +\end{verbatim} +\normalsize + +o\`u vous adapterez les directives {\bf Archive Device}, {\bf Changer Device} et +{\bf Changer Command} pour qu'elles conviennent \`a votre syst\`eme. + +\label{SpecifyingSlots} +\section{Sp\'ecifier des slots lors de l'\'etiquetage} +\index[general]{Sp\'ecifier des slots lors de l'\'etiquetage} +\index[general]{Etiquetage!Sp\'ecifier des slots lors de} + +Si vous utilisez la directive {\bf Autochanger = yes} \`a la ressource Storage +du fichier de configuration de votre Director, la console Bacula vous +demandera automatiquement le num\'ero de slot lors de l'utilisation des +commandes {\bf add} ou {\bf label} pour ce p\'eriph\'erique de stockage. Si +votre script {\bf mtx-changer} est correctement install\'e, Bacula +chargera la bonne cartouche \`a l'ex\'ecution de la commande {\bf label}. + +Vous devez aussi sp\'ecifier {\bf Autochanger = yes} dans la ressource +Device du Storage Daemon ainsi que nous l'avons d\'ecrit plus haut pour +que la librairie soit utilis\'ee. Veuillez consulter la section +\ilink{Ressource Storage}{Autochanger1} dans le chapitre sur la configuration +du Director pour plus de d\'etails sur ce sujet. + +Ainsi, toutes les phases de l'utilisation des cartouches peuvent \^etre +int\'egralement automatis\'ees. Il est aussi possible de param\'etrer ou +modifier la valeur du slot en utilisant le sous-menu {\bf Volume Parameters} +de la commande {\bf update} de la console. + +M\^eme si tous les param\`etres ci-dessus sont correctement sp\'ecifi\'es, Bacula ne +tentera d'acc\'eder \`a la librairie que s'il existe un {\bf slot} non-nul parmi +les volumes enregistr\'es dans le catalogue. + +Si votre librairie est \'equip\'ee d'un lecteur de codes barres, vous pouvez +\'etiqueter vos volumes l'un apr\`es l'autre en utilisant la commande +{\bf label barcodes}. Bacula montera et \'etiquettera chaque cartouche porteuse +d'un code barres contenue dans la librairie avec le nom sp\'ecifi\'e par le +code barres. L'enregistrement apropri\'e sera aussi cr\'e\'e dans le catalogue. +Toute cartouche dont le code barres commence par les caract\`eres sp\'ecifi\'es par +la directive {\bf Cleaning Prefix} est consid\'er\'ee comme une cartouche de +nettoyage, et ne sera pas \'etiquet\'ee. Par exemple, avec : + +\footnotesize +\begin{verbatim} +Pool { + Name ... + Cleaning Prefix = "CLN" +} +\end{verbatim} +\normalsize + +toute cartouche de code barres CLNxxxx sera trait\'ee en tant que cartouche de +nettoyage, et ne sera pas mont\'ee. + +\section{Changer des cartouches} +\index[general]{Changer des cartouches} +Si vous voulez ins\'erer ou retirer des cartouches de votre librairie, ou encore +ex\'ecuter manuellement le programme {\bf mtx}, vous devez "informer" Bacula de ces op\'erations : + +\footnotesize +\begin{verbatim} +unmount +(changez vos cartouches et/ou ex\'ecutez mtx) +mount +\end{verbatim} +\normalsize + +Si vous omettez de faire "unmount" avant de telles changements, Bacula ne saura plus +ce qui est dans la librairie, et ce qui n'y est pas, et peut m\^eme cesser de fonctionner +parce qu'il s'attend \`a avoir le contr\^ole exclusif de la librairie tandis quie le lecteur +est mont\'e. + +Notez que les volumes doivent \^etre pr\'e-\'etiquet\'es pour pouvoir \^etre utilis\'es +automatiquement dans la librairie lors d'une sauvegarde. Si vous ne disposez +pas d'un lecteur de code barres, ceci se fait manuellement, ou \`a l'aide d'un +script. + +\label{Magazines} +\section{Travailler avec plusieurs magasins} +\index[general]{Travailler avec plusieurs magasins} +\index[general]{magasins!Travailler avec plusieurs} + +Si vous avez plusieurs magasins ou si vous ins\'erez ou retirez des +cartouches d'un magasin, vous devriez en informer Bacula. Ainsi, Bacula +sera en mesure d'utiliser pr\'ef\'erentiellement des cartouches qu'il sait \^etre +dans la librairie, pr\'evenant ainsi des interventions humaines inutiles. + +Si votre librairie est \'equip\'ee d'un lecteur de codes barres, il est ais\'e +de tenir Bacula inform\'e : chaque fois que vous changez un magasin, ajoutez +ou pr\'elevez une cartouche, faites simplement : + +\footnotesize +\begin{verbatim} +unmount +(remove magazine) +(insert new magazine) +update slots +mount +\end{verbatim} +\normalsize + +dans la console. Avec cette commande, Bacula se renseigne aupr\`es de la librairie +pour conna\^itre les volumes qu'elle contient. Ceci ne n\'ecessite pas d'acc\'eder +aux volumes car la librairie se charge de faire son inventaire lors de sa +mise sous tension. Bacula s'assure alors que tout volume pr\'esent dans la +librairie est marqu\'e pr\'esent dans le catalogue et que tout volume absent de la +librairie est marqu\'e absent dans le catalogue. En outre, les num\'eros de slots +des volumes sont corrig\'es dans le catalogue s'ils sont inexacts. + +Si vous ne disposez pas d'un lecteur de codes barres, vous avez plusieurs alternatives : + +\begin{enumerate} +\item Vous pouvez attribuer manuellement les num\'eros de slots et les drapeaux + InChanger \`a l'aide de la commande {\bf update volume} dans la console. Cette + m\'ethode est assez p\'enible. + +\item Vous pouvez lancer la commande + +\footnotesize +\begin{verbatim} +update slots scan +\end{verbatim} +\normalsize + + qui ordonne \`a Bacula de lire l'\'etiquette (label) de chacune des cartouches + dans la librairie par montage successif, et de mettre \`a jour les informations + (Slot, drapeau InChanger) dans le catalogue. Cette m\'ethode est efficace, mais + prend du temps pour charger chaque cartouche et en lire l'\'etiquette. + +\item Vous pouvez modifier le script mtx-changer en sorte qu'il simule une + librairie \'equip\'ee d'un lecteur de codes barres. Voyez ce qui suit pour plus de + d\'etails +\end{enumerate} + +\label{simulating} +\section{Simuler un lecteur de codes barres dans votre librairie} +\index[general]{Librairie!Simuler un lecteur de codes barres dans votre} +\index[general]{Simuler un lecteur de codes barres dans votre} + +Vous pouvez simuler un lecteur de codes barres dans votre librairie en faisant +en sorte que le script {\bf mtx-changer} retourne les informations que +retournerait une librairie avec lecteur de codes barres. Pour cela, commentez +la ligne ci-dessous dans le "case" aux alentours de la ligne 99 : + +\footnotesize +\begin{verbatim} + ${MTX} -f $ctl status | grep " *Storage Element [0-9]*:.*Full" | awk "{print \$3 \$4}" | sed "s/Full *\(:VolumeTag=\)*//" +\end{verbatim} +\normalsize + +en ajoutant un \# au d\'ebut de cette ligne (vous pouvez aussi supprimer la ligne). +A sa place, ajoutez une nouvelle ligne dont le r\^ole est d'imprimer le contenu +d'un fichier. Par exemple : + +\footnotesize +\begin{verbatim} +cat /etc/bacula/changer.volumes +\end{verbatim} +\normalsize + +Le nom du fichier est libre, mais assurez vous d'utiliser un chemin absolu. +Le contenu du fichier doit avoir le format : + +\footnotesize +\begin{verbatim} +1:Volume1 +2:Volume2 +3:Volume3 +... +\end{verbatim} +\normalsize + +O\`u 1, 2, 3 sont les num\'eros de slots et Volume1, Volume2, Volume3 sont les +noms de volumes dans ces slots. Vous pouvez utiliser plusieurs fichiers +repr\'esentant les contenus de plusieurs magasins, ainsi, lorsque vous +changez de magasin, contentez vous de copier le contenu du fichier associ\'e +dans le fichier {\bf /etc/bacula/changer.volumes}. Il n'est pas utile de +stopper et red\'emarrer Bacula lors d'un changement de magasins, mettez simplement +les bonnes valeurs dans le fichier avant de lancer la commande {\bf update slots}. +Votre librairie appara\^itra \`a Bacula comme \'equip\'ee d'un lecteur de codes barres. + +\label{updateslots} + +\section{La forme compl\`ete de la commande Update Slots} +\index[general]{La forme compl\`ete de la commande Update Slots} +\index[general]{Command!La forme compl\`ete de la commande Update Slots} + +Si vous ne changez qu'une cartouche, vous ne voulez peut-\^etre pas passer au crible +tous vos volumes, c'est pourquoi la commande {\bf update slots} (de m\^eme que la +commande {\bf update slots scan}) poss\`ede la forme additionnelle : + +\footnotesize +\begin{verbatim} +update slots=n1,n2,n3-n4, ... +\end{verbatim} +\normalsize + +o\`u le mot-clef {\bf scan} peut \'eventuellement \^etre ajout\'e. n1, n2, n3-n4 +repr\'esentent respectivement les num\'eros et la plage de slots que vous souhaitez +mettre \`a jour. + +Cette forme est particuli\`erement utile si vous voulez utiliser "scan" (couteux en temps) +en restrignant l'op\'eration \`a quelques slots. + +Par exemple, si vous lancez la commande : + +\footnotesize +\begin{verbatim} +update slots=1,6 scan +\end{verbatim} +\normalsize + +Bacula va charger le volume du slot 6, lire son \'etiquette logicielle (label) et +mettre \`a jour le catalogue, avant de faire de m\^eme avec la cartouche du slot 6. +Avec la commande : + +\footnotesize +\begin{verbatim} +update slots=1-3,6 +\end{verbatim} +\normalsize + +il va lire les codes barres des volumes dans les slots 1,2,3 et 6, et faire les +mises \`a jour approri\'ees dans le catalogue. Si vous n'avez pas de lecteur de +codes barres, ni n'en simulez comme d\'ecrit plus haut, la commande ci-dessus +ne trouvera aucun nom de volume et ne fera donc rien. + +\label{FreeBSD} + +\section{Sp\'ecificit\'es FreeBSD} +\index[general]{Sp\'ecificit\'es!FreeBSD } +\index[general]{Sp\'ecificit\'es FreeBSD} + +Si vous rencontrez des probl\`emes sur FreeBSD lorsque Bacula tente de s\'electionner +une cartouche, et si le message est {\bf Device not configured}, c'est +parce que FreeBSD a fait dispara\^itre le fichier de p\'eriph\'erique {\bf /dev/nsa1} +lorsqu'il n'y avait plus de cartouche mont\'ee dans le lecteur. Par cons\'equent, +Bacula ne peut ouvrir le p\'eriph\'erique. Une solution consiste \`a charger une +cartouche avant le lancement de Bacula. Ce probl\`eme est corrig\'e dans les +versions de Bacula ult\'erieures \`a 1.32f-5. + +Veuillez consulter le chapitre +\ilink{Tester votre lecteur}{FreeBSDTapes} de ce manuel pour d'{\bf importantes} +informations sur votre lecteur avant de passer au test de la librairie. +\label{AutochangerTesting} + +\section{Tester la librairie et adapter le script mtx-changer} +\index[general]{Tester la librairie et adapter le script mtx-changer} +\index[general]{Script!Tester la librairie et adapter le script mtx-changer} + +Avant d'essayer d'utiliser une librairie avec Bacula, il est pr\'ef\'erable de v\'erifier +"\`a la main" que le bras robotis\'e fonctionne. Pour ce faire, utilisez les commandes +suivantes (\`a supposer que le script {\bf mtx-changer} est install\'e dans +{\bf /etc/bacula/mtx-changer}) : + +\begin{description} + +\item [Assurez vous que Bacula est stopp\'e] + +\item [/etc/bacula/mtx-changer \ /dev/sg0 \ list \ 0 \ /dev/nst0 \ 0] +\index[sd]{mtx-changer list} + +Cette commande devrait afficher : + +\footnotesize +\begin{verbatim} + 1: + 2: + 3: + ... + +\end{verbatim} +\normalsize + +soit un num\'ero suivi de deux points pour chacun des slots occup\'e dans la librairie. +Si votre librairie a un lecteur de codes barres, celui-ci sera affich\'e apr\`es les +deux points. Si un message d'erreur s'affiche, vous devez r\'esoudre le probl\`eme +(par exemple, essayez un autre nom de p\'eriph\'erique si {\bf /dev/sg0} n'est pas +le bon. PAr exemple, sur FreeBSD c'est g\'en\'eralement {\bf /dev/pass2}). + +\item [/etc/bacula/mtx-changer \ /dev/sg0 \ slots \ 0 \ /dev/nst0 \ 0] +\index[sd]{mtx-changer slots} + +Cette commande devrait retourner le nombre de slots de votre librairie. + +\item [/etc/bacula/mtx-changer \ /dev/sg0 \ unload \ ] +\index[sd]{mtx-changer unload} + +Si une cartouche est charg\'ee, cette commande devrait la d\'echarger. + +\item [/etc/bacula/mtx-changer \ /dev/sg0 \ load \ 3 \ /dev/nst0 \ 0 ] +\index[sd]{mtx-changer load} + +Si vous avez une cartouche dans le slot 3, elle sera charg\'ee dans le slot +de lecture (0). + +\item [/etc/bacula/mtx-changer \ /dev/sg0 \ loaded \ 0 \ /dev/nst0 \ 0] +\index[sd]{mtx-changer loaded} + +devrait afficher "3" + +\item [/etc/bacula/mtx-changer \ /dev/sg0 \ unload] +\end{description} + +Une fois que toutes les commandes ci-dessus fonctionnent correctement, Bacula +devrait \^etre capable d'utiliser la librairie, pourvu que votre configuration +comporte la bonne commande {\bf Changer Command}. A ce stade, il ne peut subsister +qu'un probl\`eme : si votre librairie requiert un certain d\'elai pour charger la cartouche +apr\`es l'ex\'ecution de la commande. Imm\'ediatement apr\`es avoir obtenu le retour +du script {\bf mtx-changer}, Bacula commande le rembobinage et la lecture de la bande. +S'il obtient une erreur I/O, vous devriez probablement ins\'erer une pause ({\bf sleep 20}) +apr\`es la commande {\bf mtx}, mais prenez soin de terminer le script avec un +code de sortie 0 en ajoutant {\bf exit 0} apr\`es toute commande que vous ajoutez +au script, car Bacula contr\^ole le code de sortie du script qui devrait \^etre 0 si +tout s'est bien pass\'e. + +Vous pouvez tester si vous avez ou non besoin d'une telle pause en +ex\'ecutant le script suivant : + +\footnotesize +\begin{verbatim} +#!/bin/sh +/etc/bacula/mtx-changer /dev/sg0 unload +/etc/bacula/mtx-changer /dev/sg0 load 3 +mt -f /dev/st0 rewind +mt -f /dev/st0 weof +\end{verbatim} +\normalsize + +S'il fonctionne correctement, vous n'\^etes sans doute pas concern\'e par ce +probl\`eme. Sinon, commencez par ajouter {\bf sleep 30} voire {\bf sleep 60} +juste apr\`es la commande "/etc/bacula/mtx-changer /dev/sg0 load 3". Si +\c{c}a marche, vous pouvez alors int\'egrer cette pause dans le script +{\bf mtx-changer} afin qu'elle soit effective lorsque Bacula est ex\'ecut\'e. + +Quelques rares librairies exigent l'\'ejection de la cartouche avant de pouvoir +la d\'echarger. Dan ce cas, la commande /etc/bacula/mtx-changer /dev/sg0 load 3 +ne fonctionne jamais, quel que soit la dur\'ee de la pause. Si vous pensez +avoir ce probl\`eme, ins\'erez une commande "eject" juste avant la commande +/etc/bacula/mtx-changer /dev/sg0 unload : + +\footnotesize +\begin{verbatim} +#!/bin/sh +/etc/bacula/mtx-changer /dev/sg0 unload +mt -f /dev/st0 offline +/etc/bacula/mtx-changer /dev/sg0 load 3 +mt -f /dev/st0 rewind +mt -f /dev/st0 weof +\end{verbatim} +\normalsize + +Naturellement, si vous avez besoin de la commande {\bf offline}, vous devriez +l'int\'egrer au script mtx-changer, en n'oubliant pas de pr\'eserver le code de +sortie du script par l'ajout de {\bf exit 0}. + +Comme indiqu\'e pr\'ec\'edemment, plusieurs scripts qui impl\'ementent ces fonctions +sont regroup\'es dans {\bf \lt{}bacula-source\gt{}/examples/devices}, ils +peuvent vous inspirer pour faire en sorte que le votre fonctionne. + +Si Bacula affiche "Rewind error on /dev/nst0. ERR=Input/output error." vous +avez probablement besoin d'accro\^itre la pause dans le script {\bf mtx-changer} + +\label{using} + +\section{Utiliser la librairie} +\index[general]{Utiliser la librairie} +\index[general]{Librairie!Utiliser la } + +Supposons que vous ayez convenablement d\'efini les directives Device du +Storage Daemon, et que vous ayez ajout\'e la directive {\bf Autochanger = yes} +dans la ressource Storage de votre fichier bacula-dir.conf. + +Maintenant, alimentez votre librairie avec quelques cartouches vierges. + +Que faire pour que Bacula acc\`ede \`a ces cartouches ? + +Une strat\'egie consiste \`a pr\'e-\'etiqueter chacune des cartouches. Pour cela, +d\'emarrez Bacula, puis utilisez la commande {\bf label} dans la console : + +\footnotesize +\begin{verbatim} +./console +Connecting to Director rufus:8101 +1000 OK: rufus-dir Version: 1.26 (4 October 2002) +*label +\end{verbatim} +\normalsize + +l'affichage devrait \^etre : + +\footnotesize +\begin{verbatim} +Using default Catalog name=BackupDB DB=bacula +The defined Storage resources are: + 1: Autochanger + 2: File +Select Storage resource (1-2): 1 +\end{verbatim} +\normalsize + +Choisissez la librairie (choix 1), vous obtenez : + +\footnotesize +\begin{verbatim} +Enter new Volume name: TestVolume1 +Enter slot (0 for none): 1 +\end{verbatim} +\normalsize + +Ici saisissez {\bf TestVolume1} en guise de nom, et {\bf 1} pour le slot. +On vous demande alors : + +\footnotesize +\begin{verbatim} +Defined Pools: + 1: Default + 2: File +Select the Pool (1-2): 1 +\end{verbatim} +\normalsize + +S\'electionnez le pool Default (ce qui est fait automatiquement si vous +n'avez que celui-l\`a). Bacula poursuit en d\'echargeant toute cartouche +charg\'ee, en chargeant celle du slot 1 et en l'\'etiquetant. Dans cet exemple, +le lecteur \'etait vide, il en r\'esulte l'affichage : + +\footnotesize +\begin{verbatim} +Connecting to Storage daemon Autochanger at localhost:9103 ... +Sending label command ... +3903 Issuing autochanger "load slot 1" command. +3000 OK label. Volume=TestVolume1 Device=/dev/nst0 +Media record for Volume=TestVolume1 successfully created. +Requesting mount Autochanger ... +3001 Device /dev/nst0 is mounted with Volume TestVolume1 +You have messages. +* +\end{verbatim} +\normalsize + +Vous pouvez continuer \`a \'etiqueter les autres volumes, les messages +changeront l\'eg\`erement du fait qu'il y aura cette fois une cartouche +\`a d\'echarger avant de charger la suivante. + +Une fois que tous vos volumes sont \'etiquet\'es, Bacula est en mesure de les +charger lorsqu'il en a besoin. + +Pour "voir" votre \'etiquetage, saisissez la commande {\bf list volumes} dans +la console, vous devriez obtenir quelque chose comme : + +\footnotesize +\begin{verbatim} +*{\bf list volumes} +Using default Catalog name=BackupDB DB=bacula +Defined Pools: + 1: Default + 2: File +Select the Pool (1-2): 1 ++-------+----------+--------+---------+-------+--------+----------+-------+------+ +| MedId | VolName | MedTyp | VolStat | Bites | LstWrt | VolReten | Recyc | Slot | ++-------+----------+--------+---------+-------+--------+----------+-------+------+ +| 1 | TestVol1 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 1 | +| 2 | TestVol2 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 2 | +| 3 | TestVol3 | DDS-4 | Append | 0 | 0 | 30672000 | 0 | 3 | +| ... | ++-------+----------+--------+---------+-------+--------+----------+-------+------+ +\end{verbatim} +\normalsize + +\label{Barcodes} + +\section{Support des codes barres} +\index[general]{Support!codes barres} +\index[general]{Support des codes barres} + +Bacula utilise les codes barres \`a travers deux commandes de la console : +{\bf label barcodes} et {\bf update slots}. + +La commande {\bf label barcodes} ordonne \`a Bacula de lire tous les codes +barres de toutes les cartouches pr\'esentes dans la librairie \`a l'aide de la +commande {\bf mtx-changer} {\bf list}. Les cartouches sont ensuite mont\'ees +l'une apr\`es l'autre pour \^etre \'etiquet\'e du nom de leur code barres. + +La commande {\bf update slots} commence par obtenir du script {\bf mtx-changer} +la liste des cartouches et de leurs codes barres. Ensuite, il confronte +chacune des valeurs du catalogues \`a cette liste afin de le mettre \`a jour. +Notez que si un volume ne figure pas dans le catalogue, il n'y a rien a faire. +Cette commande est utile pour synchroniser Bacula avec le contenu de la librairie +si vous avez chang\'e de magasin ou d\'eplac\'e des cartouches. + +La directive {\bf Cleaning Prefix} peut \^etre utilis\'ee dans la ressource Pool pour +d\'efinir un pr\'efixe de nom de volume qui, s'il correspond au code barres d'un volume +conf\`ere \`a ce volume le statut (VolStatus) {\bf Cleaning}. Ceci \'evite que Bacula +tente d'\'ecrire sur une cartouche de nettoyage. + +\label{interface} + +\section{Interface entre Bacula et les librairies} +\index[general]{Interface!Bacula et les librairies} +\index[general]{Interface entre Bacula et les librairies} + +Bacula appelle le script mtx-changer que vous sp\'ecifiez au niveau de la +directive {\bf Changer Command}. En principe, ce sera le script {\bf mtx-changer} +que nous fournissons, mais ce pourrait \^etre n'importe quel programme +qui impl\'emente les commandes {\bf loaded}, {\bf load}, {\bf unload}, {\bf list}, +et {\bf slots} qu'utilise Bacula. Voici le format sous lequel ces commandes +doivent retourner les informations : + +\footnotesize +\begin{verbatim} +- Currently the changer commands used are: + loaded -- retourne le num\'ero du slot d'origine de la cartouche charg\'ee, + avec pour base 1 et 0 pour le lecteur. + load -- charge la cartouche du slot sp\'ecifi\'e dans le lecteur.(notez que certains + mat\'eriels requi\`erent une pause de 30 secondes apr\`es cette commande) + unload -- d\'echarge le lecteur (la cartouche retourne dans son slot d'origine). + list -- retourne une ligne par cartouche pr\'esente dans la librairie + au format : o\`u {\bf slot} est un entier non-nul + repr\'esentant le num\'ero du slot, et {\bf barcode} est le code barres, + s'il existe et si la librairie le prend en charge, associ\'e \`a la cartouche + (dans le cas contraire, le champ "barcode" est laiss\'e blanc. + slots -- retourne le nombre total de slots dans la librairie. +\end{verbatim} +\normalsize + +Bacula contr\^ole le code de sortie du programme appel\'e. Si ce code est 0, les +informations sont accept\'ees. Dans le cas contraire, elles sont ignor\'ees +et le lecteur est trait\'e comme s'il n'\'etait pas dans une librairie. diff --git a/docs/manuals/fr/concepts/bimagemgr.bix b/docs/manuals/fr/concepts/bimagemgr.bix new file mode 100644 index 00000000..8c18e201 --- /dev/null +++ b/docs/manuals/fr/concepts/bimagemgr.bix @@ -0,0 +1,7 @@ +\indexentry {Bimagemgr }{2} +\indexentry {bimagemgr!Installation }{2} +\indexentry {bimagemgr Installation }{2} +\indexentry {bimagemgr!Usage }{4} +\indexentry {bimagemgr Usage }{4} +\indexentry {GNU Free Documentation License}{7} +\indexentry {License!GNU Free Documentation}{7} diff --git a/docs/manuals/fr/concepts/bootstrap.tex b/docs/manuals/fr/concepts/bootstrap.tex new file mode 100644 index 00000000..b69cdfbf --- /dev/null +++ b/docs/manuals/fr/concepts/bootstrap.tex @@ -0,0 +1,418 @@ +%% +%% + +\chapter{The Bootstrap File} +\label{BootstrapChapter} +\index[general]{File!Bootstrap } +\index[general]{Bootstrap File } + +The information in this chapter is provided so that you may either create your +own bootstrap files, or so that you can edit a bootstrap file produced by {\bf +Bacula}. However, normally the bootstrap file will be automatically created +for you during the +\ilink{restore\_command}{_ConsoleChapter} command in the Console program, or +by using a +\ilink{ Write Bootstrap}{writebootstrap} record in your Backup +Jobs, and thus you will never need to know the details of this file. + +The {\bf bootstrap} file contains ASCII information that permits precise +specification of what files should be restored, what volume they are on, +and where they are on the volume. It is a relatively compact +form of specifying the information, is human readable, and can be edited with +any text editor. + +\section{Bootstrap File Format} +\index[general]{Format!Bootstrap} +\index[general]{Bootstrap File Format } + +The general format of a {\bf bootstrap} file is: + +{\bf \lt{}keyword\gt{}= \lt{}value\gt{}} + +Where each {\bf keyword} and the {\bf value} specify which files to restore. +More precisely the {\bf keyword} and their {\bf values} serve to limit which +files will be restored and thus act as a filter. The absence of a keyword +means that all records will be accepted. + +Blank lines and lines beginning with a pound sign (\#) in the bootstrap file +are ignored. + +There are keywords which permit filtering by Volume, Client, Job, FileIndex, +Session Id, Session Time, ... + +The more keywords that are specified, the more selective the specification of +which files to restore will be. In fact, each keyword is {\bf AND}ed with +other keywords that may be present. + +For example, + +\footnotesize +\begin{verbatim} +Volume = Test-001 +VolSessionId = 1 +VolSessionTime = 108927638 +\end{verbatim} +\normalsize + +directs the Storage daemon (or the {\bf bextract} program) to restore only +those files on Volume Test-001 {\bf AND} having VolumeSessionId equal to one +{\bf AND} having VolumeSession time equal to 108927638. + +The full set of permitted keywords presented in the order in which they are +matched against the Volume records are: + +\begin{description} + +\item [Volume] + \index[general]{Volume } + The value field specifies what Volume the following commands apply to. + Each Volume specification becomes the current Volume, to which all the + following commands apply until a new current Volume (if any) is + specified. If the Volume name contains spaces, it should be enclosed in + quotes. At lease one Volume specification is required. + +\item [Count] + \index[general]{Count} + The value is the total number of files that will be restored for this Volume. + This allows the Storage daemon to know when to stop reading the Volume. + This value is optional. + +\item [VolFile] + \index[general]{VolFile} + The value is a file number, a list of file numbers, or a range of file + numbers to match on the current Volume. The file number represents the + physical file on the Volume where the data is stored. For a tape + volume, this record is used to position to the correct starting file, + and once the tape is past the last specified file, reading will stop. + +\item [VolBlock] + \index[general]{VolBlock} + The value is a block number, a list of block numbers, or a range of + block numbers to match on the current Volume. The block number + represents the physical block within the file on the Volume where the + data is stored. + + +\item [VolSessionTime] + \index[general]{VolSessionTime } + The value specifies a Volume Session Time to be matched from the current + volume. + +\item [VolSessionId] + \index[general]{VolSessionId } + The value specifies a VolSessionId, a list of volume session ids, or a + range of volume session ids to be matched from the current Volume. Each + VolSessionId and VolSessionTime pair corresponds to a unique Job that is + backed up on the Volume. + +\item [JobId] + \index[general]{JobId } + The value specifies a JobId, list of JobIds, or range of JobIds to be + selected from the current Volume. Note, the JobId may not be unique if you + have multiple Directors, or if you have reinitialized your database. The + JobId filter works only if you do not run multiple simultaneous jobs. + This value is optional and not used by Bacula to restore files. + +\item [Job] + \index[general]{Job } + The value specifies a Job name or list of Job names to be matched on the + current Volume. The Job corresponds to a unique VolSessionId and + VolSessionTime pair. However, the Job is perhaps a bit more readable by + humans. Standard regular expressions (wildcards) may be used to match Job + names. The Job filter works only if you do not run multiple simultaneous + jobs. + This value is optional and not used by Bacula to restore files. + +\item [Client] + \index[general]{Client } + The value specifies a Client name or list of Clients to will be matched on + the current Volume. Standard regular expressions (wildcards) may be used to + match Client names. The Client filter works only if you do not run multiple + simultaneous jobs. + This value is optional and not used by Bacula to restore files. + +\item [FileIndex] + \index[general]{FileIndex } + The value specifies a FileIndex, list of FileIndexes, or range of FileIndexes + to be selected from the current Volume. Each file (data) stored on a Volume + within a Session has a unique FileIndex. For each Session, the first file + written is assigned FileIndex equal to one and incremented for each file + backed up. + + This for a given Volume, the triple VolSessionId, VolSessionTime, and + FileIndex uniquely identifies a file stored on the Volume. Multiple copies of + the same file may be stored on the same Volume, but for each file, the triple + VolSessionId, VolSessionTime, and FileIndex will be unique. This triple is + stored in the Catalog database for each file. + + To restore a particular file, this value (or a range of FileIndexes) is + required. + +\item [Slot] + \index[general]{Slot } + The value specifies the autochanger slot. There may be only a single {\bf + Slot} specification for each Volume. + +\item [Stream] + \index[general]{Stream } + The value specifies a Stream, a list of Streams, or a range of Streams to be + selected from the current Volume. Unless you really know what you are doing + (the internals of {\bf Bacula}), you should avoid this specification. + This value is optional and not used by Bacula to restore files. + +\item [*JobType] + \index[general]{*JobType } + Not yet implemented. + +\item [*JobLevel] + \index[general]{*JobLevel } + Not yet implemented. +\end{description} + +The {\bf Volume} record is a bit special in that it must be the first record. +The other keyword records may appear in any order and any number following a +Volume record. + +Multiple Volume records may be specified in the same bootstrap file, but each +one starts a new set of filter criteria for the Volume. + +In processing the bootstrap file within the current Volume, each filter +specified by a keyword is {\bf AND}ed with the next. Thus, + +\footnotesize +\begin{verbatim} +Volume = Test-01 +Client = "My machine" +FileIndex = 1 +\end{verbatim} +\normalsize + +will match records on Volume {\bf Test-01} {\bf AND} Client records for {\bf +My machine} {\bf AND} FileIndex equal to {\bf one}. + +Multiple occurrences of the same record are {\bf OR}ed together. Thus, + +\footnotesize +\begin{verbatim} +Volume = Test-01 +Client = "My machine" +Client = "Backup machine" +FileIndex = 1 +\end{verbatim} +\normalsize + +will match records on Volume {\bf Test-01} {\bf AND} (Client records for {\bf +My machine} {\bf OR} {\bf Backup machine}) {\bf AND} FileIndex equal to {\bf +one}. + +For integer values, you may supply a range or a list, and for all other values +except Volumes, you may specify a list. A list is equivalent to multiple +records of the same keyword. For example, + +\footnotesize +\begin{verbatim} +Volume = Test-01 +Client = "My machine", "Backup machine" +FileIndex = 1-20, 35 +\end{verbatim} +\normalsize + +will match records on Volume {\bf Test-01} {\bf AND} {\bf (}Client records for +{\bf My machine} {\bf OR} {\bf Backup machine}{\bf )} {\bf AND} {\bf +(}FileIndex 1 {\bf OR} 2 {\bf OR} 3 ... {\bf OR} 20 {\bf OR} 35{\bf )}. + +As previously mentioned above, there may be multiple Volume records in the +same bootstrap file. Each new Volume definition begins a new set of filter +conditions that apply to that Volume and will be {\bf OR}ed with any other +Volume definitions. + +As an example, suppose we query for the current set of tapes to restore all +files on Client {\bf Rufus} using the {\bf query} command in the console +program: + +\footnotesize +\begin{verbatim} +Using default Catalog name=MySQL DB=bacula +*query +Available queries: + 1: List Job totals: + 2: List where a file is saved: + 3: List where the most recent copies of a file are saved: + 4: List total files/bytes by Job: + 5: List total files/bytes by Volume: + 6: List last 10 Full Backups for a Client: + 7: List Volumes used by selected JobId: + 8: List Volumes to Restore All Files: +Choose a query (1-8): 8 +Enter Client Name: Rufus ++-------+------------------+------------+-----------+----------+------------+ +| JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime | ++-------+------------------+------------+-----------+----------+------------+ +| 154 | 2002-05-30 12:08 | test-02 | 0 | 1 | 1022753312 | +| 202 | 2002-06-15 10:16 | test-02 | 0 | 2 | 1024128917 | +| 203 | 2002-06-15 11:12 | test-02 | 3 | 1 | 1024132350 | +| 204 | 2002-06-18 08:11 | test-02 | 4 | 1 | 1024380678 | ++-------+------------------+------------+-----------+----------+------------+ +\end{verbatim} +\normalsize + +The output shows us that there are four Jobs that must be restored. The first +one is a Full backup, and the following three are all Incremental backups. + +The following bootstrap file will restore those files: + +\footnotesize +\begin{verbatim} +Volume=test-02 +VolSessionId=1 +VolSessionTime=1022753312 +Volume=test-02 +VolSessionId=2 +VolSessionTime=1024128917 +Volume=test-02 +VolSessionId=1 +VolSessionTime=1024132350 +Volume=test-02 +VolSessionId=1 +VolSessionTime=1024380678 +\end{verbatim} +\normalsize + +As a final example, assume that the initial Full save spanned two Volumes. The +output from {\bf query} might look like: + +\footnotesize +\begin{verbatim} ++-------+------------------+------------+-----------+----------+------------+ +| JobId | StartTime | VolumeName | StartFile | VolSesId | VolSesTime | ++-------+------------------+------------+-----------+----------+------------+ +| 242 | 2002-06-25 16:50 | File0003 | 0 | 1 | 1025016612 | +| 242 | 2002-06-25 16:50 | File0004 | 0 | 1 | 1025016612 | +| 243 | 2002-06-25 16:52 | File0005 | 0 | 2 | 1025016612 | +| 246 | 2002-06-25 19:19 | File0006 | 0 | 2 | 1025025494 | ++-------+------------------+------------+-----------+----------+------------+ +\end{verbatim} +\normalsize + +and the following bootstrap file would restore those files: + +\footnotesize +\begin{verbatim} +Volume=File0003 +VolSessionId=1 +VolSessionTime=1025016612 +Volume=File0004 +VolSessionId=1 +VolSessionTime=1025016612 +Volume=File0005 +VolSessionId=2 +VolSessionTime=1025016612 +Volume=File0006 +VolSessionId=2 +VolSessionTime=1025025494 +\end{verbatim} +\normalsize + +\section{Automatic Generation of Bootstrap Files} +\index[general]{Files!Automatic Generation of Bootstrap } +\index[general]{Automatic Generation of Bootstrap Files } + +One thing that is probably worth knowing: the bootstrap files that are +generated automatically at the end of the job are not as optimized as those +generated by the restore command. This is because during Incremental and +Differential jobs, the records pertaining to the files written for the +Job are appended to the end of the bootstrap file. +As consequence, all the files saved to an Incremental or Differential job will be +restored first by the Full save, then by any Incremental or Differential +saves. + +When the bootstrap file is generated for the restore command, only one copy +(the most recent) of each file is restored. + +So if you have spare cycles on your machine, you could optimize the bootstrap +files by doing the following: + +\footnotesize +\begin{verbatim} + ./bconsole + restore client=xxx select all + done + no + quit + Backup bootstrap file. +\end{verbatim} +\normalsize + +The above will not work if you have multiple FileSets because that will be an +extra prompt. However, the {\bf restore client=xxx select all} builds the +in-memory tree, selecting everything and creates the bootstrap file. + +The {\bf no} answers the {\bf Do you want to run this (yes/mod/no)} question. + +\label{bscanBootstrap} +\section{Bootstrap for bscan} +\index[general]{bscan} +\index[general]{bscan!bootstrap} +\index[general]{bscan bootstrap} +If you have a very large number of Volumes to scan with {\bf bscan}, +you may exceed the command line limit (511 characters). I that case, +you can create a simple bootstrap file that consists of only the +volume names. An example might be: + +\footnotesize +\begin{verbatim} +Volume="Vol001" +Volume="Vol002" +Volume="Vol003" +Volume="Vol004" +Volume="Vol005" +\end{verbatim} +\normalsize + + +\section{A Final Bootstrap Example} +\index[general]{Bootstrap Example} +\index[general]{Example!Bootstrap} + +If you want to extract or copy a single Job, you can do it by selecting by +JobId (code not tested) or better yet, if you know the VolSessionTime and the +VolSessionId (printed on Job report and in Catalog), specifying this is by far +the best. Using the VolSessionTime and VolSessionId is the way Bacula does +restores. A bsr file might look like the following: + +\footnotesize +\begin{verbatim} +Volume="Vol001" +VolSessionId=10 +VolSessionTime=1080847820 +\end{verbatim} +\normalsize + +If you know how many files are backed up (on the job report), you can +enormously speed up the selection by adding (let's assume there are 157 +files): + +\footnotesize +\begin{verbatim} +FileIndex=1-157 +Count=157 +\end{verbatim} +\normalsize + +Finally, if you know the File number where the Job starts, you can also cause +bcopy to forward space to the right file without reading every record: + +\footnotesize +\begin{verbatim} +VolFile=20 +\end{verbatim} +\normalsize + +There is nothing magic or complicated about a BSR file. Parsing it and +properly applying it within Bacula *is* magic, but you don't need to worry +about that. + +If you want to see a *real* bsr file, simply fire up the {\bf restore} command +in the console program, select something, then answer no when it prompts to +run the job. Then look at the file {\bf restore.bsr} in your working +directory. diff --git a/docs/manuals/fr/concepts/bugs.tex b/docs/manuals/fr/concepts/bugs.tex new file mode 100644 index 00000000..42df829d --- /dev/null +++ b/docs/manuals/fr/concepts/bugs.tex @@ -0,0 +1,21 @@ +%% +%% + +\section{Bacula Bugs} +\label{BugsChapter} +\index[general]{Bacula Bugs } +\index[general]{Bugs!Bacula } + +Well fortunately there are not too many bugs, but thanks to Dan Langille, we +have a +\elink{bugs database}{http://bugs.bacula.org} where bugs are reported. +Generally, when a bug is fixed, a patch for the currently released version will +be attached to the bug report. + +The directory {\bf patches} in the current SVN always contains a list of +the patches that have been created for the previously released version +of Bacula. In addition, the file {\bf patches-version-number} in the +{\bf patches} directory contains a summary of each of the patches. + +A "raw" list of the current task list and known issues can be found in {\bf +kernstodo} in the main Bacula source directory. diff --git a/docs/manuals/fr/concepts/check_tex.pl b/docs/manuals/fr/concepts/check_tex.pl new file mode 100755 index 00000000..e12d51be --- /dev/null +++ b/docs/manuals/fr/concepts/check_tex.pl @@ -0,0 +1,152 @@ +#!/usr/bin/perl -w +# Finds potential problems in tex files, and issues warnings to the console +# about what it finds. Takes a list of files as its only arguments, +# and does checks on all the files listed. The assumption is that these are +# valid (or close to valid) LaTeX files. It follows \include statements +# recursively to pick up any included tex files. +# +# +# +# Currently the following checks are made: +# +# -- Multiple hyphens not inside a verbatim environment (or \verb). These +# should be placed inside a \verb{} contruct so they will not be converted +# to single hyphen by latex and latex2html. + + +# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com +# +# + +use strict; + +# The following builds the test string to identify and change multiple +# hyphens in the tex files. Several constructs are identified but only +# multiple hyphens are changed; the others are fed to the output +# unchanged. +my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{ +my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{ +my $c = '\\s*\\}'; # closing curly brace + +# This captures entire verbatim environments. These are passed to the output +# file unchanged. +my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c; + +# This captures \verb{..{ constructs. They are passed to the output unchanged. +my $verb = '\\\\verb\\*?(.).*?\\1'; + +# This captures multiple hyphens with a leading and trailing space. These are not changed. +my $hyphsp = '\\s\\-{2,}\\s'; + +# This identifies other multiple hyphens. +my $hyphens = '\\-{2,}'; + +# This identifies \hyperpage{..} commands, which should be ignored. +my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}'; + +# This builds the actual test string from the above strings. +#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens"; +my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens"; + + +sub get_includes { + # Get a list of include files from the top-level tex file. The first + # argument is a pointer to the list of files found. The rest of the + # arguments is a list of filenames to check for includes. + my $files = shift; + my ($fileline,$includefile,$includes); + + while (my $filename = shift) { + # Get a list of all the html files in the directory. + open my $if,"<$filename" or die "Cannot open input file $filename\n"; + $fileline = 0; + $includes = 0; + while (<$if>) { + chomp; + $fileline++; + # If a file is found in an include, process it. + if (($includefile) = /\\include\s*\{(.*?)\}/) { + $includes++; + # Append .tex to the filename + $includefile .= '.tex'; + + # If the include file has already been processed, issue a warning + # and don't do it again. + my $found = 0; + foreach (@$files) { + if ($_ eq $includefile) { + $found = 1; + last; + } + } + if ($found) { + print "$includefile found at line $fileline in $filename was previously included\n"; + } else { + # The file has not been previously found. Save it and + # recursively process it. + push (@$files,$includefile); + get_includes($files,$includefile); + } + } + } + close IF; + } +} + + +sub check_hyphens { + my (@files) = @_; + my ($filedata,$this,$linecnt,$before); + + # Build the test string to check for the various environments. + # We only do the conversion if the multiple hyphens are outside of a + # verbatim environment (either \begin{verbatim}...\end{verbatim} or + # \verb{--}). Capture those environments and pass them to the output + # unchanged. + + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # Set up to process the file data. + $linecnt = 1; + + # Go through the file data from beginning to end. For each match, save what + # came before it and what matched. $filedata now becomes only what came + # after the match. + # Chech the match to see if it starts with a multiple-hyphen. If so + # warn the user. Keep track of line numbers so they can be output + # with the warning message. + while ($filedata =~ /$teststr/os) { + $this = $&; + $before = $`; + $filedata = $'; + $linecnt += $before =~ tr/\n/\n/; + + # Check if the multiple hyphen is present outside of one of the + # acceptable constructs. + if ($this =~ /^\-+/) { + print "Possible unwanted multiple hyphen found in line ", + "$linecnt of file $file\n"; + } + $linecnt += $this =~ tr/\n/\n/; + } + } +} +################################################################## +# MAIN #### +################################################################## + +my (@includes,$cnt); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +get_includes(\@includes,@ARGV); + +check_hyphens(@includes); diff --git a/docs/manuals/fr/concepts/concepts.tex b/docs/manuals/fr/concepts/concepts.tex new file mode 100644 index 00000000..c4f4b08c --- /dev/null +++ b/docs/manuals/fr/concepts/concepts.tex @@ -0,0 +1,115 @@ +%% +%% +%% The following characters must be preceded by a backslash +%% to be entered as printable characters: +%% +%% # $ % & ~ _ ^ \ { } +%% + +\documentclass[11pt,a4paper]{book} +\usepackage{html} +\usepackage{float} +\usepackage{graphicx} +\usepackage{bacula} +\usepackage{longtable} +\usepackage{makeidx} +\usepackage{index} +\usepackage{setspace} +\usepackage{hyperref} +\usepackage{url} + + +\makeindex +\newindex{dir}{ddx}{dnd}{Director Index} +\newindex{fd}{fdx}{fnd}{File Daemon Index} +\newindex{sd}{sdx}{snd}{Storage Daemon Index} +\newindex{console}{cdx}{cnd}{Console Index} +\newindex{general}{idx}{ind}{General Index} + +\sloppy + +\begin{document} +\sloppy + +\newfont{\bighead}{cmr17 at 36pt} +\parskip 10pt +\parindent 0pt + +\title{\includegraphics{./bacula-logo.eps} \\ \bigskip + \Huge{Bacula Concepts and Overview Guide} + \begin{center} + \large{It comes in the night and sucks + the essence from your computers. } + \end{center} +} + + +\author{Kern Sibbald} +\date{\vspace{1.0in}\today \\ + This manual documents Bacula version \input{version} \\ + \vspace{0.2in} + Copyright \copyright 1999-2007, Free Software Foundation Europe + e.V. \\ + \vspace{0.2in} + Permission is granted to copy, distribute and/or modify this document under the terms of the + GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU Free Documentation License". +} + +\maketitle + +\clearpage +\pagenumbering{roman} +\tableofcontents +\clearpage +\listoffigures +\clearpage +\listoftables +\clearpage + +\markboth{Bacula Manual}{} +\pagenumbering{arabic} +\include{general} +\include{state} +\include{requirements} +\include{supportedoses} +\include{supporteddrives} +\include{tutorial} +\include{restore} +\include{recycling} +\include{disk} +\include{dvd} +\include{pools} +\include{migration} +\include{strategies} +\include{autochangers} +\include{supportedchangers} +\include{spooling} +\include{python} +\include{ansi-labels} +\include{win32} +\include{rescue} +\include{tls} +\include{dataencryption} +\include{verify} +\include{bootstrap} +\include{license} +\include{fdl} +\include{gpl} +\include{lesser} +\include{projects} +\include{thanks} +\include{bugs} +\include{vars} +\include{stunnel} + +% pull in the index +\clearpage +\printindex[general] +\printindex[dir] +\printindex[fd] +\printindex[sd] +\printindex[console] + +\end{document} diff --git a/docs/manuals/fr/concepts/dataencryption.tex b/docs/manuals/fr/concepts/dataencryption.tex new file mode 100644 index 00000000..34b050fe --- /dev/null +++ b/docs/manuals/fr/concepts/dataencryption.tex @@ -0,0 +1,195 @@ + +\chapter{Data Encryption} +\label{DataEncryption} +\index[general]{Data Encryption} +\index[general]{Encryption!Data} +\index[general]{Data Encryption} + +Bacula permits file data encryption and signing within the File Daemon (or +Client) prior to sending data to the Storage Daemon. Upon restoration, +file signatures are validated and any mismatches are reported. At no time +does the Director or the Storage Daemon have access to unencrypted file +contents. + + +It is very important to specify what this implementation does NOT +do: +\begin{itemize} +\item There is one important restore problem to be aware of, namely, it's + possible for the director to restore new keys or a Bacula configuration + file to the client, and thus force later backups to be made with a + compromised key and/or with no encryption at all. You can avoid this by + not not changing the location of the keys in your Bacula File daemon + configuration file, and not changing your File daemon keys. If you do + change either one, you must ensure that no restore is done that restores + the old configuration or the old keys. In general, the worst effect of + this will be that you can no longer connect the File daemon. + +\item The implementation does not encrypt file metadata such as file path + names, permissions, and ownership. Extended attributes are also currently + not encrypted. However, Mac OS X resource forks are encrypted. +\end{itemize} + +Encryption and signing are implemented using RSA private keys coupled with +self-signed x509 public certificates. This is also sometimes known as PKI +or Public Key Infrastructure. + +Each File Daemon should be given its own unique private/public key pair. +In addition to this key pair, any number of "Master Keys" may be specified +-- these are key pairs that may be used to decrypt any backups should the +File Daemon key be lost. Only the Master Key's public certificate should +be made available to the File Daemon. Under no circumstances should the +Master Private Key be shared or stored on the Client machine. + +The Master Keys should be backed up to a secure location, such as a CD +placed in a in a fire-proof safe or bank safety deposit box. The Master +Keys should never be kept on the same machine as the Storage Daemon or +Director if you are worried about an unauthorized party compromising either +machine and accessing your encrypted backups. + +While less critical than the Master Keys, File Daemon Keys are also a prime +candidate for off-site backups; burn the key pair to a CD and send the CD +home with the owner of the machine. + +NOTE!!! If you lose your encryption keys, backups will be unrecoverable. +{\bf ALWAYS} store a copy of your master keys in a secure, off-site location. + +The basic algorithm used for each backup session (Job) is: +\begin{enumerate} +\item The File daemon generates a session key. +\item The FD encrypts that session key via PKE for all recipients (the file +daemon, any master keys). +\item The FD uses that session key to perform symmetric encryption on the data. +\end{enumerate} + + +\section{Building Bacula with Encryption Support} +\index[general]{Building Bacula with Encryption Support} + +The configuration option for enabling OpenSSL encryption support has not changed +since Bacula 1.38. To build Bacula with encryption support, you will need +the OpenSSL libraries and headers installed. When configuring Bacula, use: + +\begin{verbatim} + ./configure --with-openssl ... +\end{verbatim} + +\section{Encryption Technical Details} +\index[general]{Encryption Technical Details} + +The implementation uses 128bit AES-CBC, with RSA encrypted symmetric +session keys. The RSA key is user supplied. +If you are running OpenSSL 0.9.8 or later, the signed file hash uses +SHA-256 -- otherwise, SHA-1 is used. + +End-user configuration settings for the algorithms are not currently +exposed -- only the algorithms listed above are used. However, the +data written to Volume supports arbitrary symmetric, asymmetric, and +digest algorithms for future extensibility, and the back-end +implementation currently supports: + +\begin{verbatim} +Symmetric Encryption: + - 128, 192, and 256-bit AES-CBC + - Blowfish-CBC + +Asymmetric Encryption (used to encrypt symmetric session keys): + - RSA + +Digest Algorithms: + - MD5 + - SHA1 + - SHA256 + - SHA512 +\end{verbatim} + +The various algorithms are exposed via an entirely re-usable, +OpenSSL-agnostic API (ie, it is possible to drop in a new encryption +backend). The Volume format is DER-encoded ASN.1, modeled after the +Cryptographic Message Syntax from RFC 3852. Unfortunately, using CMS +directly was not possible, as at the time of coding a free software +streaming DER decoder/encoder was not available. + + +\section{Decrypting with a Master Key} +\index[general]{Decrypting with a Master Key} + +It is preferable to retain a secure, non-encrypted copy of the +client's own encryption keypair. However, should you lose the +client's keypair, recovery with the master keypair is possible. + +You must: +\begin{itemize} +\item Concatenate the master private and public key into a single + keypair file, ie: + cat master.key master.cert >master.keypair + +\item 2) Set the PKI Keypair statement in your bacula configuration file: + +\begin{verbatim} + PKI Keypair = master.keypair +\end{verbatim} + +\item Start the restore. The master keypair will be used to decrypt + the file data. + +\end{itemize} + + +\section{Generating Private/Public Encryption Keys} +\index[general]{Generating Private/Public Encryption Keypairs} + +Generate a Master Key Pair with: + +\footnotesize +\begin{verbatim} + openssl genrsa -out master.key 2048 + openssl req -new -key master.key -x509 -out master.cert +\end{verbatim} +\normalsize + +Generate a File Daemon Key Pair for each FD: + +\footnotesize +\begin{verbatim} + openssl genrsa -out fd-example.key 2048 + openssl req -new -key fd-example.key -x509 -out fd-example.cert + cat fd-example.key fd-example.cert >fd-example.pem +\end{verbatim} +\normalsize + +Note, there seems to be a lot of confusion around the file extensions given +to these keys. For example, a .pem file can contain all the following: +private keys (RSA and DSA), public keys (RSA and DSA) and (x509) certificates. +It is the default format for OpenSSL. It stores data Base64 encoded DER format, +surrounded by ASCII headers, so is suitable for text mode transfers between +systems. A .pem file may contain any number of keys either public or +private. We use it in cases where there is both a public and a private +key. + +Typically, above we have used the .cert extension to refer to X509 +certificate encoding that contains only a single public key. + + +\section{Example Data Encryption Configuration} +\index[general]{Example!File Daemon Configuration File} +\index[general]{Example!Data Encryption Configuration File} +\index[general]{Example Data Encryption Configuration} + +{\bf bacula-fd.conf} +\footnotesize +\begin{verbatim} +FileDaemon { + Name = example-fd + FDport = 9102 # where we listen for the director + WorkingDirectory = /var/bacula/working + Pid Directory = /var/run + Maximum Concurrent Jobs = 20 + + PKI Signatures = Yes # Enable Data Signing + PKI Encryption = Yes # Enable Data Encryption + PKI Keypair = "/etc/bacula/fd-example.pem" # Public and Private Keys + PKI Master Key = "/etc/bacula/master.cert" # ONLY the Public Key +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/concepts/disk.tex b/docs/manuals/fr/concepts/disk.tex new file mode 100644 index 00000000..3f38be9f --- /dev/null +++ b/docs/manuals/fr/concepts/disk.tex @@ -0,0 +1,789 @@ +%% +%% + +\chapter{Basic Volume Management} +\label{DiskChapter} +\index[general]{Basic Volume Management} +\index[general]{Management!Basic Volume} +\index[general]{Disk Volumes} + +This chapter presents most all the features needed to do Volume management. +Most of the concepts apply equally well to both tape and disk Volumes. +However, the chapter was originally written to explain backing up to disk, so +you will see it is slanted in that direction, but all the directives +presented here apply equally well whether your volume is disk or tape. + +If you have a lot of hard disk storage or you absolutely must have your +backups run within a small time window, you may want to direct Bacula to +backup to disk Volumes rather than tape Volumes. This chapter is intended to +give you some of the options that are available to you so that you can manage +either disk or tape volumes. + +\label{Concepts} +\section{Key Concepts and Resource Records} +\index[general]{Key Concepts and Resource Records } +\index[general]{Records!Key Concepts and Resource } + +Getting Bacula to write to disk rather than tape in the simplest case is +rather easy. In the Storage daemon's configuration file, you simply define an +{\bf Archive Device} to be a directory. For example, if you want your disk +backups to go into the directory {\bf /home/bacula/backups}, you could use the +following: + +\footnotesize +\begin{verbatim} +Device { + Name = FileBackup + Media Type = File + Archive Device = /home/bacula/backups + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} +\end{verbatim} +\normalsize + +Assuming you have the appropriate {\bf Storage} resource in your Director's +configuration file that references the above Device resource, + +\footnotesize +\begin{verbatim} +Storage { + Name = FileStorage + Address = ... + Password = ... + Device = FileBackup + Media Type = File +} +\end{verbatim} +\normalsize + +Bacula will then write the archive to the file {\bf +/home/bacula/backups/\lt{}volume-name\gt{}} where \lt{}volume-name\gt{} is the +volume name of a Volume defined in the Pool. For example, if you have labeled +a Volume named {\bf Vol001}, Bacula will write to the file {\bf +/home/bacula/backups/Vol001}. Although you can later move the archive file to +another directory, you should not rename it or it will become unreadable by +Bacula. This is because each archive has the filename as part of the internal +label, and the internal label must agree with the system filename before +Bacula will use it. + +Although this is quite simple, there are a number of problems. The first is +that unless you specify otherwise, Bacula will always write to the same volume +until you run out of disk space. This problem is addressed below. + +In addition, if you want to use concurrent jobs that write to several +different volumes at the same time, you will need to understand a number +of other details. An example of such a configuration is given +at the end of this chapter under \ilink{Concurrent Disk +Jobs}{ConcurrentDiskJobs}. + +\subsection{Pool Options to Limit the Volume Usage} +\index[general]{Usage!Pool Options to Limit the Volume } +\index[general]{Pool Options to Limit the Volume Usage } + +Some of the options you have, all of which are specified in the Pool record, +are: + +\begin{itemize} +\item To write each Volume only once (i.e. one Job per Volume or file in this + case), use: + +{\bf UseVolumeOnce = yes}. + +\item To write nnn Jobs to each Volume, use: + + {\bf Maximum Volume Jobs = nnn}. + +\item To limit the maximum size of each Volume, use: + + {\bf Maximum Volume Bytes = mmmm}. + + Note, if you use disk volumes, with all versions up to and including + 1.39.28, you should probably limit the Volume size to some reasonable + value such as say 5GB. This is because during a restore, Bacula is + currently unable to seek to the proper place in a disk volume to restore + a file, which means that it must read all records up to where the + restore begins. If your Volumes are 50GB, reading half or more of the + volume could take quite a bit of time. Also, if you ever have a partial + hard disk failure, you are more likely to be able to recover more data + if they are in smaller Volumes. + +\item To limit the use time (i.e. write the Volume for a maximum of five days), + use: + +{\bf Volume Use Duration = ttt}. +\end{itemize} + +Note that although you probably would not want to limit the number of bytes on +a tape as you would on a disk Volume, the other options can be very useful in +limiting the time Bacula will use a particular Volume (be it tape or disk). +For example, the above directives can allow you to ensure that you rotate +through a set of daily Volumes if you wish. + +As mentioned above, each of those directives is specified in the Pool or +Pools that you use for your Volumes. In the case of {\bf Maximum Volume Job}, +{\bf Maximum Volume Bytes}, and {\bf Volume Use Duration}, you can actually +specify the desired value on a Volume by Volume basis. The value specified in +the Pool record becomes the default when labeling new Volumes. Once a Volume +has been created, it gets its own copy of the Pool defaults, and subsequently +changing the Pool will have no effect on existing Volumes. You can either +manually change the Volume values, or refresh them from the Pool defaults using +the {\bf update volume} command in the Console. As an example +of the use of one of the above, suppose your Pool resource contains: + +\footnotesize +\begin{verbatim} +Pool { + Name = File + Pool Type = Backup + Volume Use Duration = 23h +} +\end{verbatim} +\normalsize + +then if you run a backup once a day (every 24 hours), Bacula will use a new +Volume for each backup, because each Volume it writes can only be used for 23 hours +after the first write. Note, setting the use duration to 23 hours is not a very +good solution for tapes unless you have someone on-site during the weekends, +because Bacula will want a new Volume and no one will be present to mount it, +so no weekend backups will be done until Monday morning. + +\label{AutomaticLabeling} +\subsection{Automatic Volume Labeling} +\index[general]{Automatic Volume Labeling } +\index[general]{Labeling!Automatic Volume } + +Use of the above records brings up another problem -- that of labeling your +Volumes. For automated disk backup, you can either manually label each of your +Volumes, or you can have Bacula automatically label new Volumes when they are +needed. While, the automatic Volume labeling in version 1.30 and prior is a +bit simplistic, but it does allow for automation, the features added in +version 1.31 permit automatic creation of a wide variety of labels including +information from environment variables and special Bacula Counter variables. +In version 1.37 and later, it is probably much better to use Python scripting +and the NewVolume event since generating Volume labels in a Python script is +much easier than trying to figure out Counter variables. See the +\ilink{Python Scripting}{PythonChapter} chapter of this manual for more +details. + +Please note that automatic Volume labeling can also be used with tapes, but +it is not nearly so practical since the tapes must be pre-mounted. This +requires some user interaction. Automatic labeling from templates does NOT +work with autochangers since Bacula will not access unknown slots. There +are several methods of labeling all volumes in an autochanger magazine. +For more information on this, please see the \ilink{ +Autochanger}{AutochangersChapter} chapter of this manual. + +Automatic Volume labeling is enabled by making a change to both the Pool +resource (Director) and to the Device resource (Storage daemon) shown above. +In the case of the Pool resource, you must provide Bacula with a label format +that it will use to create new names. In the simplest form, the label format +is simply the Volume name, to which Bacula will append a four digit number. +This number starts at 0001 and is incremented for each Volume the catalog +contains. Thus if you modify your Pool resource to be: + +\footnotesize +\begin{verbatim} +Pool { + Name = File + Pool Type = Backup + Volume Use Duration = 23h + LabelFormat = "Vol" +} +\end{verbatim} +\normalsize + +Bacula will create Volume names Vol0001, Vol0002, and so on when new Volumes +are needed. Much more complex and elaborate labels can be created using +variable expansion defined in the +\ilink{Variable Expansion}{VarsChapter} chapter of this manual. + +The second change that is necessary to make automatic labeling work is to give +the Storage daemon permission to automatically label Volumes. Do so by adding +{\bf LabelMedia = yes} to the Device resource as follows: + +\footnotesize +\begin{verbatim} +Device { + Name = File + Media Type = File + Archive Device = /home/bacula/backups + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; + LabelMedia = yes +} +\end{verbatim} +\normalsize + +You can find more details of the {\bf Label Format} Pool record in +\ilink{Label Format}{Label} description of the Pool resource +records. + +\label{Recycling1} +\subsection{Restricting the Number of Volumes and Recycling} +\index[general]{Recycling!Restricting the Number of Volumes and Recycling} +\index[general]{Restricting the Number of Volumes and Recycling} + +Automatic labeling discussed above brings up the problem of Volume management. +With the above scheme, a new Volume will be created every day. If you have not +specified Retention periods, your Catalog will continue to fill keeping track +of all the files Bacula has backed up, and this procedure will create one new +archive file (Volume) every day. + +The tools Bacula gives you to help automatically manage these problems are the +following: + +\begin{enumerate} +\item Catalog file record retention periods, the + \ilink{File Retention = ttt}{FileRetention} record in the Client + resource. +\item Catalog job record retention periods, the + \ilink{Job Retention = ttt}{JobRetention} record in the Client + resource. +\item The + \ilink{ AutoPrune = yes}{AutoPrune} record in the Client resource + to permit application of the above two retention periods. +\item The + \ilink{ Volume Retention = ttt}{VolRetention} record in the Pool + resource. +\item The + \ilink{ AutoPrune = yes}{PoolAutoPrune} record in the Pool + resource to permit application of the Volume retention period. +\item The + \ilink{ Recycle = yes}{PoolRecycle} record in the Pool resource + to permit automatic recycling of Volumes whose Volume retention period has + expired. +\item The + \ilink{ Recycle Oldest Volume = yes}{RecycleOldest} record in the + Pool resource tells Bacula to Prune the oldest volume in the Pool, and if all + files were pruned to recycle this volume and use it. +\item The + \ilink{ Recycle Current Volume = yes}{RecycleCurrent} record in + the Pool resource tells Bacula to Prune the currently mounted volume in the + Pool, and if all files were pruned to recycle this volume and use it. +\item The + \ilink{ Purge Oldest Volume = yes}{PurgeOldest} record in the + Pool resource permits a forced recycling of the oldest Volume when a new one + is needed. {\bf N.B. This record ignores retention periods! We highly + recommend not to use this record, but instead use Recycle Oldest Volume} +\item The + \ilink{ Maximum Volumes = nnn}{MaxVolumes} record in the Pool + resource to limit the number of Volumes that can be created. +\end{enumerate} + +The first three records (File Retention, Job Retention, and AutoPrune) +determine the amount of time that Job and File records will remain in your +Catalog, and they are discussed in detail in the +\ilink{Automatic Volume Recycling}{RecyclingChapter} chapter of +this manual. + +Volume Retention, AutoPrune, and Recycle determine how long Bacula will keep +your Volumes before reusing them, and they are also discussed in detail in the +\ilink{Automatic Volume Recycling}{RecyclingChapter} chapter of +this manual. + +The Maximum Volumes record can also be used in conjunction with the Volume +Retention period to limit the total number of archive Volumes (files) that +Bacula will create. By setting an appropriate Volume Retention period, a +Volume will be purged just before it is needed and thus Bacula can cycle +through a fixed set of Volumes. Cycling through a fixed set of Volumes can +also be done by setting {\bf Recycle Oldest Volume = yes} or {\bf Recycle +Current Volume = yes}. In this case, when Bacula needs a new Volume, it will +prune the specified volume. + +\label{ConcurrentDiskJobs} +\section{Concurrent Disk Jobs} +\index[general]{Concurrent Disk Jobs} +Above, we discussed how you could have a single device named {\bf +FileBackup} that writes to volumes in {\bf /home/bacula/backups}. +You can, in fact, run multiple concurrent jobs using the +Storage definition given with this example, and all the jobs will +simultaneously write into the Volume that is being written. + +Now suppose you want to use multiple Pools, which means multiple +Volumes, or suppose you want each client to have its own Volume +and perhaps its own directory such as {\bf /home/bacula/client1} +and {\bf /home/bacula/client2} ... With the single Storage and Device +definition above, neither of these two is possible. Why? Because +Bacula disk storage follows the same rules as tape devices. Only +one Volume can be mounted on any Device at any time. If you want +to simultaneously write multiple Volumes, you will need multiple +Device resources in your bacula-sd.conf file, and thus multiple +Storage resources in your bacula-dir.conf. + +OK, so now you should understand that you need multiple Device definitions +in the case of different directories or different Pools, but you also +need to know that the catalog data that Bacula keeps contains only +the Media Type and not the specific storage device. This permits a tape +for example to be re-read on any compatible tape drive. The compatibility +being determined by the Media Type. The same applies to disk storage. +Since a volume that is written by a Device in say directory {\bf +/home/bacula/backups} cannot be read by a Device with an Archive Device +definition of {\bf /home/bacula/client1}, you will not be able to +restore all your files if you give both those devices +{\bf Media Type = File}. During the restore, Bacula will simply choose +the first available device, which may not be the correct one. If this +is confusing, just remember that the Directory has only the Media Type +and the Volume name. It does not know the {\bf Archive Device} (or the +full path) that is specified in the Storage daemon. Thus you must +explicitly tie your Volumes to the correct Device by using the Media Type. + +The example shown below shows a case where there are two clients, each +using its own Pool and storing their Volumes in different directories. + + +\label{Example2} +\section{An Example} +\index[general]{Example } + +The following example is not very practical, but can be used to demonstrate +the proof of concept in a relatively short period of time. The example +consists of a two clients that are backed up to a set of 12 archive files +(Volumes) for each client into different directories on the Storage +machine. Each Volume is used (written) only once, and there are four Full +saves done every hour (so the whole thing cycles around after three hours). + +What is key here is that each physical device on the Storage daemon +has a different Media Type. This allows the Director to choose the +correct device for restores ... + +The Director's configuration file is as follows: + +\footnotesize +\begin{verbatim} +Director { + Name = my-dir + QueryFile = "~/bacula/bin/query.sql" + PidDirectory = "~/bacula/working" + WorkingDirectory = "~/bacula/working" + Password = dir_password +} +Schedule { + Name = "FourPerHour" + Run = Level=Full hourly at 0:05 + Run = Level=Full hourly at 0:20 + Run = Level=Full hourly at 0:35 + Run = Level=Full hourly at 0:50 +} +Job { + Name = "RecycleExample" + Type = Backup + Level = Full + Client = Rufus + FileSet= "Example FileSet" + Messages = Standard + Storage = FileStorage + Pool = Recycle + Schedule = FourPerHour +} + +Job { + Name = "RecycleExample2" + Type = Backup + Level = Full + Client = Roxie + FileSet= "Example FileSet" + Messages = Standard + Storage = FileStorage1 + Pool = Recycle1 + Schedule = FourPerHour +} + +FileSet { + Name = "Example FileSet" + Include = compression=GZIP signature=SHA1 { + /home/kern/bacula/bin + } +} +Client { + Name = Rufus + Address = rufus + Catalog = BackupDB + Password = client_password +} + +Client { + Name = Roxie + Address = roxie + Catalog = BackupDB + Password = client1_password +} + +Storage { + Name = FileStorage + Address = rufus + Password = local_storage_password + Device = RecycleDir + Media Type = File +} + +Storage { + Name = FileStorage1 + Address = rufus + Password = local_storage_password + Device = RecycleDir1 + Media Type = File1 +} + +Catalog { + Name = BackupDB + dbname = bacula; user = bacula; password = "" +} +Messages { + Name = Standard + ... +} +Pool { + Name = Recycle + Use Volume Once = yes + Pool Type = Backup + LabelFormat = "Recycle-" + AutoPrune = yes + VolumeRetention = 2h + Maximum Volumes = 12 + Recycle = yes +} + +Pool { + Name = Recycle1 + Use Volume Once = yes + Pool Type = Backup + LabelFormat = "Recycle1-" + AutoPrune = yes + VolumeRetention = 2h + Maximum Volumes = 12 + Recycle = yes +} + +\end{verbatim} +\normalsize + +and the Storage daemon's configuration file is: + +\footnotesize +\begin{verbatim} +Storage { + Name = my-sd + WorkingDirectory = "~/bacula/working" + Pid Directory = "~/bacula/working" + MaximumConcurrentJobs = 10 +} +Director { + Name = my-dir + Password = local_storage_password +} +Device { + Name = RecycleDir + Media Type = File + Archive Device = /home/bacula/backups + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} + +Device { + Name = RecycleDir1 + Media Type = File1 + Archive Device = /home/bacula/backups1 + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} + +Messages { + Name = Standard + director = my-dir = all +} +\end{verbatim} +\normalsize + +With a little bit of work, you can change the above example into a weekly or +monthly cycle (take care about the amount of archive disk space used). + +\label{MultipleDisks} +\section{Backing up to Multiple Disks} +\index[general]{Disks!Backing up to Multiple } +\index[general]{Backing up to Multiple Disks } + +Bacula can, of course, use multiple disks, but in general, each disk must be a +separate Device specification in the Storage daemon's conf file, and you must +then select what clients to backup to each disk. You will also want to +give each Device specification a different Media Type so that during +a restore, Bacula will be able to find the appropriate drive. + +The situation is a bit more complicated if you want to treat two different +physical disk drives (or partitions) logically as a single drive, which +Bacula does not directly support. However, it is possible to back up your +data to multiple disks as if they were a single drive by linking the +Volumes from the first disk to the second disk. + +For example, assume that you have two disks named {\bf /disk1} and {\bf +/disk2}. If you then create a standard Storage daemon Device resource for +backing up to the first disk, it will look like the following: + +\footnotesize +\begin{verbatim} +Device { + Name = client1 + Media Type = File + Archive Device = /disk1 + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} +\end{verbatim} +\normalsize + +Since there is no way to get the above Device resource to reference both {\bf +/disk1} and {\bf /disk2} we do it by pre-creating Volumes on /disk2 with the +following: + +\footnotesize +\begin{verbatim} +ln -s /disk2/Disk2-vol001 /disk1/Disk2-vol001 +ln -s /disk2/Disk2-vol002 /disk1/Disk2-vol002 +ln -s /disk2/Disk2-vol003 /disk1/Disk2-vol003 +... +\end{verbatim} +\normalsize + +At this point, you can label the Volumes as Volume {\bf Disk2-vol001}, {\bf +Disk2-vol002}, ... and Bacula will use them as if they were on /disk1 but +actually write the data to /disk2. The only minor inconvenience with this +method is that you must explicitly name the disks and cannot use automatic +labeling unless you arrange to have the labels exactly match the links you +have created. + +An important thing to know is that Bacula treats disks like tape drives +as much as it can. This means that you can only have a single Volume +mounted at one time on a disk as defined in your Device resource in +the Storage daemon's conf file. You can have multiple concurrent +jobs running that all write to the one Volume that is being used, but +if you want to have multiple concurrent jobs that are writing to +separate disks drives (or partitions), you will need to define +separate Device resources for each one, exactly as you would do for +two different tape drives. There is one fundamental difference, however. +The Volumes that you create on the two drives cannot be easily exchanged +as they can for a tape drive, because they are physically resident (already +mounted in a sense) on the particular drive. As a consequence, you will +probably want to give them different Media Types so that Bacula can +distinguish what Device resource to use during a restore. +An example would be the following: + +\footnotesize +\begin{verbatim} +Device { + Name = Disk1 + Media Type = File1 + Archive Device = /disk1 + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} + +Device { + Name = Disk2 + Media Type = File2 + Archive Device = /disk2 + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} +\end{verbatim} +\normalsize + +With the above device definitions, you can run two concurrent +jobs each writing at the same time, one to {\bf /disk2} and the +other to {\bf /disk2}. The fact that you have given them different +Media Types will allow Bacula to quickly choose the correct +Storage resource in the Director when doing a restore. + +\label{MultipleClients} +\section{Considerations for Multiple Clients} +\index[general]{Clients!Considerations for Multiple } +\index[general]{Multiple Clients} + +If we take the above example and add a second Client, here are a few +considerations: + +\begin{itemize} +\item Although the second client can write to the same set of Volumes, you + will probably want to write to a different set. +\item You can write to a different set of Volumes by defining a second Pool, + which has a different name and a different {\bf LabelFormat}. +\item If you wish the Volumes for the second client to go into a different + directory (perhaps even on a different filesystem to spread the load), you + would do so by defining a second Device resource in the Storage daemon. The +{\bf Name} must be different, and the {\bf Archive Device} could be +different. To ensure that Volumes are never mixed from one pool to another, +you might also define a different MediaType (e.g. {\bf File1}). +\end{itemize} + +In this example, we have two clients, each with a different Pool and a +different number of archive files retained. They also write to different +directories with different Volume labeling. + +The Director's configuration file is as follows: + +\footnotesize +\begin{verbatim} +Director { + Name = my-dir + QueryFile = "~/bacula/bin/query.sql" + PidDirectory = "~/bacula/working" + WorkingDirectory = "~/bacula/working" + Password = dir_password +} +# Basic weekly schedule +Schedule { + Name = "WeeklySchedule" + Run = Level=Full fri at 1:30 + Run = Level=Incremental sat-thu at 1:30 +} +FileSet { + Name = "Example FileSet" + Include = compression=GZIP signature=SHA1 { + /home/kern/bacula/bin + } +} +Job { + Name = "Backup-client1" + Type = Backup + Level = Full + Client = client1 + FileSet= "Example FileSet" + Messages = Standard + Storage = File1 + Pool = client1 + Schedule = "WeeklySchedule" +} +Job { + Name = "Backup-client2" + Type = Backup + Level = Full + Client = client2 + FileSet= "Example FileSet" + Messages = Standard + Storage = File2 + Pool = client2 + Schedule = "WeeklySchedule" +} +Client { + Name = client1 + Address = client1 + Catalog = BackupDB + Password = client1_password + File Retention = 7d +} +Client { + Name = client2 + Address = client2 + Catalog = BackupDB + Password = client2_password +} +# Two Storage definitions with different Media Types +# permits different directories +Storage { + Name = File1 + Address = rufus + Password = local_storage_password + Device = client1 + Media Type = File1 +} +Storage { + Name = File2 + Address = rufus + Password = local_storage_password + Device = client2 + Media Type = File2 +} +Catalog { + Name = BackupDB + dbname = bacula; user = bacula; password = "" +} +Messages { + Name = Standard + ... +} +# Two pools permits different cycling periods and Volume names +# Cycle through 15 Volumes (two weeks) +Pool { + Name = client1 + Use Volume Once = yes + Pool Type = Backup + LabelFormat = "Client1-" + AutoPrune = yes + VolumeRetention = 13d + Maximum Volumes = 15 + Recycle = yes +} +# Cycle through 8 Volumes (1 week) +Pool { + Name = client2 + Use Volume Once = yes + Pool Type = Backup + LabelFormat = "Client2-" + AutoPrune = yes + VolumeRetention = 6d + Maximum Volumes = 8 + Recycle = yes +} +\end{verbatim} +\normalsize + +and the Storage daemon's configuration file is: + +\footnotesize +\begin{verbatim} +Storage { + Name = my-sd + WorkingDirectory = "~/bacula/working" + Pid Directory = "~/bacula/working" + MaximumConcurrentJobs = 10 +} +Director { + Name = my-dir + Password = local_storage_password +} +# Archive directory for Client1 +Device { + Name = client1 + Media Type = File1 + Archive Device = /home/bacula/client1 + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} +# Archive directory for Client2 +Device { + Name = client2 + Media Type = File2 + Archive Device = /home/bacula/client2 + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} +Messages { + Name = Standard + director = my-dir = all +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/concepts/do_echo b/docs/manuals/fr/concepts/do_echo new file mode 100644 index 00000000..04b9f79a --- /dev/null +++ b/docs/manuals/fr/concepts/do_echo @@ -0,0 +1,6 @@ +# +# Avoid that @VERSION@ and @DATE@ are changed by configure +# This file is sourced by update_version +# +echo "s%@VERSION@%${VERSION}%g" >${out} +echo "s%@DATE@%${DATE}%g" >>${out} diff --git a/docs/manuals/fr/concepts/dvd.tex b/docs/manuals/fr/concepts/dvd.tex new file mode 100644 index 00000000..f11e70d6 --- /dev/null +++ b/docs/manuals/fr/concepts/dvd.tex @@ -0,0 +1,329 @@ +%% +%% + +\chapter{DVD Volumes} +\label{_DVDChapterStart} +\index[general]{DVD Volumes} +\index[general]{Writing DVDs} +\index[general]{DVD Writing} +\index[general]{Volumes!DVD} + +Bacula allows you to specify that you want to write to DVD. However, +this feature is implemented only in version 1.37 or later. +You may in fact write to DVD+RW, DVD+R, DVD-R, or DVD-RW +media. The actual process used by Bacula is to first write +the image to a spool directory, then when the Volume reaches +a certain size or, at your option, at the end of a Job, Bacula +will transfer the image from the spool directory to the +DVD. The actual work of transferring the image is done +by a script {\bf dvd-handler}, and the heart of that +script is a program called {\bf growisofs} which allows +creating or adding to a DVD ISO filesystem. + +You must have {\bf dvd+rw-tools} loaded on your system for DVD writing to +work. Please note that the original {\bf dvd+rw-tools} package does {\bf +NOT} work with Bacula. You must apply a patch which can be found in the +{\bf patches} directory of Bacula sources with the name +{\bf dvd+rw-tools-5.21.4.10.8.bacula.patch} for version 5.21 of the tools, +or patch {bf dvd+rw-tools-6.1.bacula.patch} if you have version 6.1 +on your system. Unfortunately, this requires you to build the dvd\_rw-tools +from source. + +Note, some Linux distros such as Debian dvd+rw-tools-7.0-4 package already +have the patch applied, so please check. + +The fact that Bacula cannot use the OS to write directly +to the DVD makes the whole process a bit more error prone than +writing to a disk or a tape, but nevertheless, it does work if you +use some care to set it up properly. However, at the current time +(version 1.39.30 -- 12 December 2006) we still consider this code to be +BETA quality. As a consequence, please do careful testing before relying +on DVD backups in production. + +The remainder of this chapter explains the various directives that you can +use to control the DVD writing. + +\label{DVDdirectives} +\section{DVD Specific SD Directives} +\index[general]{Directives!DVD} +\index[general]{DVD Specific SD Directives } + +The following directives are added to the Storage daemon's +Device resource. + +\begin{description} + +\item [Requires Mount = {\it Yes|No}] + \index[sd]{Requires Mount } + You must set this directive to {\bf yes} for DVD-writers, and to {\bf no} for + all other devices (tapes/files). This directive indicates if the device + requires to be mounted using the {\bf Mount Command}. + To be able to write a DVD, the following directives must also be + defined: {\bf Mount Point}, {\bf Mount Command}, {\bf Unmount Command} and + {\bf Write Part Command}. + +\item [Mount Point = {\it directory}] + \index[sd]{Mount Point} + Directory where the device can be mounted. + +\item [Mount Command = {\it name-string}] + \index[sd]{Mount Command} + Command that must be executed to mount the device. Although the + device is written directly, the mount command is necessary in + order to determine the free space left on the DVD. Before the command is + executed, \%a is replaced with the Archive Device, and \%m with the Mount + Point. + + Most frequently, you will define it as follows: + +\footnotesize +\begin{verbatim} + Mount Command = "/bin/mount -t iso9660 -o ro %a %m" +\end{verbatim} +\normalsize + +However, if you have defined a mount point in /etc/fstab, you might be +able to use a mount command such as: + +\footnotesize +\begin{verbatim} + Mount Command = "/bin/mount /media/dvd" +\end{verbatim} +\normalsize + + +\item [Unmount Command = {\it name-string}] + \index[sd]{Unmount Command} + Command that must be executed to unmount the device. Before the command is + executed, \%a is replaced with the Archive Device, and \%m with the Mount + Point. + + Most frequently, you will define it as follows: + +\footnotesize +\begin{verbatim} + Unmount Command = "/bin/umount %m" +\end{verbatim} +\normalsize + +\item [Write Part Command = {\it name-string}] + \index[sd]{Write Part Command } + Command that must be executed to write a part to the device. Before the + command is executed, \%a is replaced with the Archive Device, \%m with the + Mount Point, \%e is replaced with 1 if we are writing the first part, + and with 0 otherwise, and \%v with the current part filename. + + For a DVD, you will most frequently specify the Bacula supplied {\bf + dvd-handler} script as follows: + +\footnotesize +\begin{verbatim} + Write Part Command = "/path/dvd-handler %a write %e %v" +\end{verbatim} +\normalsize + + Where {\bf /path} is the path to your scripts install directory, and + dvd-handler is the Bacula supplied script file. + This command will already be present, but commented out, + in the default bacula-sd.conf file. To use it, simply remove + the comment (\#) symbol. + + +\item [Free Space Command = {\it name-string}] + \index[sd]{Free Space Command } + Command that must be executed to check how much free space is left on the + device. Before the command is executed,\%a is replaced with the Archive + Device. + + For a DVD, you will most frequently specify the Bacula supplied {\bf + dvd-handler} script as follows: + +\footnotesize +\begin{verbatim} + Free Space Command = "/path/dvd-handler %a free" +\end{verbatim} +\normalsize + + Where {\bf /path} is the path to your scripts install directory, and + dvd-freespace is the Bacula supplied script file. + If you want to specify your own command, please look at the code in + dvd-handler to see what output Bacula expects from this command. + This command will already be present, but commented out, + in the default bacula-sd.conf file. To use it, simply remove + the comment (\#) symbol. + + If you do not set it, Bacula will expect there is always free space on the + device. + +\end{description} + +In addition to the directives specified above, you must also +specify the other standard Device resource directives. Please see the +sample DVD Device resource in the default bacula-sd.conf file. Be sure +to specify the raw device name for {\bf Archive Device}. It should +be a name such as {\bf /dev/cdrom} or {\bf /media/cdrecorder} or +{\bf /dev/dvd} depending on your system. It will not be a name such +as {\bf /mnt/cdrom}. + +Finally, for {\bf growisofs} to work, it must be able to lock +a certain amount of memory in RAM. If you have restrictions on +this function, you may have failures. Under {\bf bash}, you can +set this with the following command: + +\footnotesize +\begin{verbatim} +ulimit -l unlimited +\end{verbatim} +\normalsize + +\section{Edit Codes for DVD Directives} +\index[general]{Directives!DVD Edit Codes} +\index[general]{Edit Codes for DVD Directives } + +Before submitting the {\bf Mount Command}, {\bf Unmount Command}, +{\bf Write Part Command}, or {\bf Free Space Command} directives +to the operating system, Bacula performs character substitution of the +following characters: + +\footnotesize +\begin{verbatim} + %% = % + %a = Archive device name + %e = erase (set if cannot mount and first part) + %n = part number + %m = mount point + %v = last part name (i.e. filename) +\end{verbatim} +\normalsize + + + +\section{DVD Specific Director Directives} +\index[general]{Directives!DVD} +\index[general]{DVD Specific Director Directives } + +The following directives are added to the Director's Job resource. + +\label{WritePartAfterJob} +\begin{description} +\item [Write Part After Job = \lt{}yes|no\gt{}] + \index[dir]{Write Part After Job } + If this directive is set to {\bf yes} (default {\bf no}), the + Volume written to a temporary spool file for the current Job will + be written to the DVD as a new part file + will be created after the job is finished. + + It should be set to {\bf yes} when writing to devices that require a mount + (for example DVD), so you are sure that the current part, containing + this job's data, is written to the device, and that no data is left in + the temporary file on the hard disk. However, on some media, like DVD+R + and DVD-R, a lot of space (about 10Mb) is lost everytime a part is + written. So, if you run several jobs each after another, you could set + this directive to {\bf no} for all jobs, except the last one, to avoid + wasting too much space, but to ensure that the data is written to the + medium when all jobs are finished. + + This directive is ignored for devices other than DVDs. +\end{description} + + + +\label{DVDpoints} +\section{Other Points} +\index[general]{Points!Other } +\index[general]{Other Points } + +\begin{itemize} +\item Please be sure that you have any automatic DVD mounting + disabled before running Bacula -- this includes auto mounting + in /etc/fstab, hotplug, ... If the DVD is automatically + mounted by the OS, it will cause problems when Bacula tries + to mount/unmount the DVD. +\item Please be sure that you the directive {\bf Write Part After Job} + set to {\bf yes}, otherwise the last part of the data to be + written will be left in the DVD spool file and not written to + the DVD. The DVD will then be unreadable until this last part + is written. If you have a series of jobs that are run one at + a time, you can turn this off until the last job is run. +\item The current code is not designed to have multiple simultaneous + jobs writing to the DVD. As a consequence, please ensure that + only one DVD backup job runs at any time. +\item Writing and reading of DVD+RW seems to work quite reliably + provided you are using the patched dvd+rw-mediainfo programs. + On the other hand, we do not have enough information to ensure + that DVD-RW or other forms of DVDs work correctly. +\item DVD+RW supports only about 1000 overwrites. Every time you + mount the filesystem read/write will count as one write. This can + add up quickly, so it is best to mount your DVD+RW filesystem read-only. + Bacula does not need the DVD to be mounted read-write, since it uses + the raw device for writing. +\item Reformatting DVD+RW 10-20 times can apparently make the medium + unusable. Normally you should not have to format or reformat + DVD+RW media. If it is necessary, current versions of growisofs will + do so automatically. +\item We have had several problems writing to DVD-RWs (this does NOT + concern DVD+RW), because these media have two writing-modes: {\bf + Incremental Sequential} and {\bf Restricted Overwrite}. Depending on + your device and the media you use, one of these modes may not work + correctly (e.g. {\bf Incremental Sequential} does not work with my NEC + DVD-writer and Verbatim DVD-RW). + + To retrieve the current mode of a DVD-RW, run: +\begin{verbatim} + dvd+rw-mediainfo /dev/xxx +\end{verbatim} + where you replace xxx with your DVD device name. + + {\bf Mounted Media} line should give you the information. + + To set the device to {\bf Restricted Overwrite} mode, run: +\begin{verbatim} + dvd+rw-format /dev/xxx +\end{verbatim} + If you want to set it back to the default {\bf Incremental Sequential} mode, run: +\begin{verbatim} + dvd+rw-format -blank /dev/xxx +\end{verbatim} + +\item Bacula only accepts to write to blank DVDs. To quickly blank a DVD+/-RW, run + this command: +\begin{verbatim} + dd if=/dev/zero bs=1024 count=512 | growisofs -Z /dev/xxx=/dev/fd/0 +\end{verbatim} + Then, try to mount the device, if it cannot be mounted, it will be considered + as blank by Bacula, if it can be mounted, try a full blank (see below). + +\item If you wish to blank completely a DVD+/-RW, use the following: +\begin{verbatim} + growisofs -Z /dev/xxx=/dev/zero +\end{verbatim} + where you replace xxx with your DVD device name. However, note that this + blanks the whole DVD, which takes quite a long time (16 minutes on mine). +\item DVD+RW and DVD-RW support only about 1000 overwrites (i.e. don't use the +same medium for years if you don't want to have problems...). + +To write to the DVD the first time use: +\begin{verbatim} + growisofs -Z /dev/xxx filename +\end{verbatim} + +To add additional files (more parts use): + +\begin{verbatim} + growisofs -M /dev/xxx filename +\end{verbatim} + +The option {\bf -use-the-force-luke=4gms} was added in growisofs 5.20 to +override growisofs' behavior of always checking for the 4GB limit. +Normally, this option is recommended for all Linux 2.6.8 kernels or +greater, since these newer kernels can handle writing more than 4GB. +See below for more details on this subject. + +\item For more information about DVD writing, please look at the +\elink{dvd+rw-tools homepage}{http://fy.chalmers.se/~appro/linux/DVD+RW/}. + +\item According to bug \#912, bscan cannot read multi-volume DVDs. This is +on our TODO list, but unless someone submits a patch it is not likely to be +done any time in the near future. (9 Sept 2007). + +\end{itemize} diff --git a/docs/manuals/fr/concepts/fdl.tex b/docs/manuals/fr/concepts/fdl.tex new file mode 100644 index 00000000..b46cd990 --- /dev/null +++ b/docs/manuals/fr/concepts/fdl.tex @@ -0,0 +1,485 @@ +% TODO: maybe get rid of centering + +\chapter{GNU Free Documentation License} +\index[general]{GNU Free Documentation License} +\index[general]{License!GNU Free Documentation} + +\label{label_fdl} + + \begin{center} + + Version 1.2, November 2002 + + + Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc. + + \bigskip + + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + \bigskip + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +\end{center} + + +\begin{center} +{\bf\large Preamble} +\end{center} + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +\begin{center} +{\Large\bf 1. APPLICABILITY AND DEFINITIONS} +\end{center} + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The \textbf{"Document"}, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as \textbf{"you"}. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A \textbf{"Modified Version"} of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A \textbf{"Secondary Section"} is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The \textbf{"Cover Texts"} are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A \textbf{"Transparent"} copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called \textbf{"Opaque"}. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The \textbf{"Title Page"} means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as \textbf{"Acknowledgements"}, +\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.) +To \textbf{"Preserve the Title"} +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +\begin{center} +{\Large\bf 2. VERBATIM COPYING} +\end{center} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\begin{center} +{\Large\bf 3. COPYING IN QUANTITY} +\end{center} + + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\begin{center} +{\Large\bf 4. MODIFICATIONS} +\end{center} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} +\item[A.] + Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. + +\item[B.] + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + +\item[C.] + State on the Title page the name of the publisher of the + Modified Version, as the publisher. + +\item[D.] + Preserve all the copyright notices of the Document. + +\item[E.] + Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + +\item[F.] + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + +\item[G.] + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. + +\item[H.] + Include an unaltered copy of this License. + +\item[I.] + Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + +\item[J.] + Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + +\item[K.] + For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + +\item[L.] + Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. + +\item[M.] + Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + +\item[N.] + Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. + +\item[O.] + Preserve any Warranty Disclaimers. +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\begin{center} +{\Large\bf 5. COMBINING DOCUMENTS} +\end{center} + + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + +\begin{center} +{\Large\bf 6. COLLECTIONS OF DOCUMENTS} +\end{center} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +\begin{center} +{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS} +\end{center} + + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +\begin{center} +{\Large\bf 8. TRANSLATION} +\end{center} + + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +\begin{center} +{\Large\bf 9. TERMINATION} +\end{center} + + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\begin{center} +{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE} +\end{center} + + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +\begin{center} +{\Large\bf ADDENDUM: How to use this License for your documents} +% TODO: this is too long for table of contents +\end{center} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\bigskip +\begin{quote} + Copyright \copyright YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +\end{quote} +\bigskip + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + +\bigskip +\begin{quote} + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. +\end{quote} +\bigskip + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +%--------------------------------------------------------------------- diff --git a/docs/manuals/fr/concepts/fix_tex.pl b/docs/manuals/fr/concepts/fix_tex.pl new file mode 100755 index 00000000..98657576 --- /dev/null +++ b/docs/manuals/fr/concepts/fix_tex.pl @@ -0,0 +1,184 @@ +#!/usr/bin/perl -w +# Fixes various things within tex files. + +use strict; + +my %args; + + +sub get_includes { + # Get a list of include files from the top-level tex file. + my (@list,$file); + + foreach my $filename (@_) { + $filename or next; + # Start with the top-level latex file so it gets checked too. + push (@list,$filename); + + # Get a list of all the html files in the directory. + open IF,"<$filename" or die "Cannot open input file $filename"; + while () { + chomp; + push @list,"$1.tex" if (/\\include\{(.*?)\}/); + } + + close IF; + } + return @list; +} + +sub convert_files { + my (@files) = @_; + my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt); + + $cnt = 0; + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # We look for a line that starts with \item, and indent the two next lines (if not blank) + # by three spaces. + my $linecnt = 3; + $indentcnt = 0; + $output = ""; + # Process a line at a time. + foreach (split(/\n/,$filedata)) { + $_ .= "\n"; # Put back the return. + # If this line is less than the third line past the \item command, + # and the line isn't blank and doesn't start with whitespace + # add three spaces to the start of the line. Keep track of the number + # of lines changed. + if ($linecnt < 3 and !/^\\item/) { + if (/^[^\n\s]/) { + $output .= " " . $_; + $indentcnt++; + } else { + $output .= $_; + } + $linecnt++; + } else { + $linecnt = 3; + $output .= $_; + } + /^\\item / and $linecnt = 1; + } + + + # This is an item line. We need to process it too. If inside a \begin{description} environment, convert + # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'. + $itemcnt = 0; + $filedata = $output; + $output = ""; + my ($before,$descrip,$this,$between); + + # Find any \begin{description} environment + while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) { + $output .= $` . $1; + $filedata = $3 . $'; + $descrip = $2; + + # Search for \item {\bf xxx} + while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) { + $descrip = $'; + $output .= $`; + ($between,$descrip) = find_matching_brace($descrip); + if (!$descrip) { + $linecnt = $output =~ tr/\n/\n/; + print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip); + } + + # Now do the replacement. + $between = '{' . $between . '}' if ($between =~ /\[|\]/); + $output .= "\\item \[$between\]"; + $itemcnt++; + } + $output .= $descrip; + } + $output .= $filedata; + + # If any hyphens or \item commnads were converted, save the file. + if ($indentcnt or $itemcnt) { + open OF,">$file" or die "Cannot open output file $file"; + print OF $output; + close OF; + print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n"; + print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n"; + } + + $cnt += $indentcnt + $itemcnt; + } + return $cnt; +} + +sub find_matching_brace { + # Finds text up to the next matching brace. Assumes that the input text doesn't contain + # the opening brace, but we want to find text up to a matching closing one. + # Returns the text between the matching braces, followed by the rest of the text following + # (which does not include the matching brace). + # + my $str = shift; + my ($this,$temp); + my $cnt = 1; + + while ($cnt) { + # Ignore verbatim constructs involving curly braces, or if the character preceding + # the curly brace is a backslash. + if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) { + $this .= $`; + $str = $'; + $temp = $&; + + if ((substr($this,-1,1) eq '\\') or + $temp =~ /^\\verb/) { + $this .= $temp; + next; + } + + $cnt += ($temp eq '{') ? 1 : -1; + # If this isn't the matching curly brace ($cnt > 0), include the brace. + $this .= $temp if ($cnt); + } else { + # No matching curly brace found. + return ($this . $str,''); + } + } + return ($this,$str); +} + +sub check_arguments { + # Checks command-line arguments for ones starting with -- puts them into + # a hash called %args and removes them from @ARGV. + my $args = shift; + my $i; + + for ($i = 0; $i < $#ARGV; $i++) { + $ARGV[$i] =~ /^\-+/ or next; + $ARGV[$i] =~ s/^\-+//; + $args{$ARGV[$i]} = ""; + delete ($ARGV[$i]); + + } +} + +################################################################## +# MAIN #### +################################################################## + +my @includes; +my $cnt; + +check_arguments(\%args); +die "No Files given to Check\n" if ($#ARGV < 0); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +@includes = get_includes(@ARGV); + +$cnt = convert_files(@includes); +print "No lines changed\n" unless $cnt; diff --git a/docs/manuals/fr/concepts/general.tex b/docs/manuals/fr/concepts/general.tex new file mode 100644 index 00000000..977f699e --- /dev/null +++ b/docs/manuals/fr/concepts/general.tex @@ -0,0 +1,554 @@ +%% +%% + +\chapter{Qu'est-ce que Bacula ?} +\label{_ChapterStart41} +\index[general]{Qu'est-ce que Bacula ? } +\index[general]{Bacula!Qu'est-ce que } +\addcontentsline{toc}{section}{Qu'est-ce que Bacula ?} + +{\bf Bacula} est un jeu de programmes qui vous permet (ou \`a l'administrateur +syst\`eme) de faire des sauvegardes, restaurations, et v\'erifications des +donn\'ees d'un ordinateur sur un r\'eseau h\'et\'erog\`ene. Bacula peut +fonctionner compl\`etement sur un seul ordinateur. Il est capable de +sauvegarder sur des supports vari\'es, y compris disques et cartouches. + +En termes +techniques, il s'agit d'un programme de sauvegarde Client/Serveur. Bacula est +relativement facile d'utilisation et efficace, tout en offant de nombreuses +fonctions avanc\'ees de gestion de stockage qui facilitent la recherche et la +restauration de fichiers perdus ou endommag\'es. Gr\^ace \`a sa conception +modulaire, Bacula est \'echelonnable depuis le simple syst\`eme constitu\'e +d'un ordinateur, jusqu'au syst\`eme de plusieurs centaines d'ordinateurs +diss\'emin\'es sur un vaste r\'eseau. + +\section{Qui a besoin de Bacula ?} +\index[general]{Qui a besoin de Bacula ? } +\index[general]{Bacula!Qui a besoin de } +\addcontentsline{toc}{section}{Qui a besoin de Bacula ?} + +Si vous utilisez actuellement un programme tel que {\bf tar}, {\bf dump}, ou +{\bf bru} pour sauvegarder vos donn\'ees, et aimeriez une solution r\'eseau, +plus de flexibilit\'e, ou les commodit\'es d'un catalogue, Bacula vous +procurera certainement les fonctions suppl\'ementaires que vous recherchez. +Cependant, si vous avez peu d'exp\'erience des syst\`emes Unix ou si vous +n'avez pas l'exp\'erience d'un syst\`eme de sauvegarde sophistiqu\'e, nous ne +vous recommandons pas l'utilisation de Bacula, car il est beaucoup plus +difficile \`a installer et utiliser que {\bf tar} ou {\bf dump}. + +Si vous attendez de Bacula qu'il se comporte comme les programmes simples +mentionn\'es ci-dessus et qu'il \'ecrive sur toute cartouche ins\'er\'ee dans le +lecteur, vous \'eprouverez des difficult\'es \`a travailler avec Bacula. Bacula +est con\c {c}u pour prot\'eger vos donn\'ees en suivant les r\`egles que vous sp\'ecifiez, +ce qui signifie que la r\'eutilisation d'une cartouche ne se fera qu'en dernier +ressort. Il est possible de "contraindre" Bacula \`a \'ecraser toute cartouche dans +le lecteur, mais il est plus facile et plus efficace d'utiliser un outil +plus basique pour ce genre d'op\'erations. + +Si vous utilisez {\bf Amanda} et aimeriez un programme de sauvegarde qui peut +\'ecrire sur plusieurs volumes (qui ne soit pas limit\'e par la capacit\'e de vos +cartouches), Bacula peut certainement satisfaire vos besoins, d'autant que +plusieurs de nos utilisateurs estiment que Bacula est plus simple \`a +installer et utiliser que d'autres programmes \'equivalents. + +Si vous utilisez actuellement un logiciel commercial sophistiqu\'e tel que +{\bf Legato Networker}, {\bf ARCserveIT}, {\bf Arkeia}, ou {\bf +PerfectBackup+}, vous pourriez \^etre interess\'e par Bacula qui fournit la +plupart de leurs fonctions et qui est un logiciel libre sous licence GNU +version 2. + +\section{Composants ou Services de Bacula} +\index[general]{Bacula!Composants ou Services de } +\index[general]{Composants ou Services de Bacula } +\addcontentsline{toc}{section}{Composants ou Services de Bacula} + +Bacula est constitu\'e des cinq composants ou services majeurs suivants : + +\includegraphics{./bacula-applications.eps} +(remerciements \`a Aristedes Maniatis pour ce sch\'ema et le suivant) + +\begin{itemize} +\item + \label{DirDef} + Le service {\bf Bacula Director +\label{a1} +} est le programme qui supervise toutes les op\'erations de sauvegarde, +restauration, v\'erification et archivage. L'administrateur syst\`eme utilise +le Bacula Director pour planifier les sauvegardes et restaurer les fichiers. +Pour plus de d\'etails, consultez la section concernant la conception du Daemon Director +dans la documentation pour d\'eveloppeurs. Le Director est ex\'ecut\'e en tant que {\it daemon} +ou service (c'est \`a dire en tâche de fond). +\item + \label{UADef} + Le service {\bf Bacula Console} est le programme qui permet \`a +l'administrateur ou \`a l'utilisateur de communiquer avec le {\bf Bacula +Director} (voir ci-dessus). Actuellement, le service Bacula Console est +disponible en trois versions. La premi\`ere et la plus simple est +d'ex\'ecuter le programme Console dans une fen\^etre shell (i.e. interface +TTY). La plupart des administrateurs syst\`eme trouveront cette m\'ethode +parfaitement ad\'equate. La seconde version est une interface graphique GNOME +qui est loin d'\^etre compl\`ete, mais est +tout \`a fait fonctionnelle puisqu'elle poss\`ede la plupart des +possibilit\'es de la Console shell. La troisi\`eme version est une interface +graphique wxWidgets qui permet de s\'electionner interactivement les fichiers +\`a restaurer. Elle int\`egre la plupart des fonctionnalit\'es de la console +shell, permet la compl\'etion automatique avec la touche tabulation, et +fournit une aide instantan\'ee relative \`a la commande que vous \^etes en +train de taper. Pour plus de d\'etails, consultez la section +\ilink{Conception de la Console Bacula}{_ConsoleChapter} dans la documentation +pour d\'eveloppeurs. +\item + \label{FDDef} + Le service {\bf Bacula File} (ou programme client) est le programme install\'e +sur la machine \`a sauvegarder. Il est sp\'ecifique au syst\`eme sur lequel +il est ex\'ecut\'e et a la charge de fournir les attributs des fichiers et +les donn\'ees requis par le Director. Les Services File sont aussi charg\'es +de la partie d\'ependant du syst\`eme de fichiers lors de la restauration des +attributs de fichiers et des donn\'ees. Pour plus de d\'etails, consultez le +document sur la conception du File Daemon dans le Guide pour Developpeurs. Ce +programme est ex\'ecut\'e en tant que service sur la machine \`a sauvegarder, +et la documentation s'y r\'ef\`ere parfois en tant que Client (par exemple +dans les fichiers de configuration de Bacula). En plus du File Daemon pour +Unix/Linux, il existe un File Daemon pour Windows (usuellement distribu\'e au +format binaire). Le File Daemon Windows fonctionne sur toutes les versions +actuelles de Windows (NT, 2000, XP, 2003 et peut-\^etre aussi 98 et Me). +\item + \label{SDDef} + Le service {\bf Bacula Storage} est le programme qui transf\`ere les donn\'ees +et les attributs de fichiers aux m\'edia physiques ou aux volumes et les +restitue lors de restaurations. En d'autres termes, Le storage Daemon est +responsable des op\'erations de lecture et d'\'ecriture sur vos cartouches (ou +autres m\'edia de stockage, comme par exemple des fichiers). Pour plus de +d\'etails consultez la Documentation Pour D\'eveloppeurs sur la conception du +Storage Daemon. +\item + \label{DBDefinition} + Les services {\bf Catalogue} ont pour t\^ache de maintenir \`a jour la base de +donn\'ees des index de fichiers et volumes pour tous les fichiers +sauvegard\'es. Les services {\bf Catalogue} permettent \`a l'administrateur +syst\`eme ou \`a l'utilisateur de localiser rapidement et restaurer n'importe +quel fichier. Les services Catalogue de Bacula le placent dans une +cat\'egorie diff\'erente de programmes tels que tar et bru, puisque le +catalogue Bacula maintient un enregistrement de chaque volume utilis\'e, +chaque job ex\'ecut\'e et chaque fichier sauvegard\'e ce qui permet des +restaurations et une gestion de volumes efficaces. Bacula supporte +actuellement trois bases de donn\'ees diff\'erentes, MySQL, PostgreSQL, et +SQLite. L'une des trois doit \^etre choisie \`a la compilation de {\bf +Bacula}. + +Les trois bases de donn\'ees actuellement support\'ees (MySQL, PostgreSQL, ou +SQLite) fournissent de nombreuses fonctions telles l'indexation rapide, +requ\^etes arbitraires, et s\'ecurit\'e. Bien que nous pr\'evoyions de +supporter d'autres bases de donn\'ees SQL majeures, l'impl\'ementation +actuelle s'interface seulement avec MySQL, PostgreSQL, et SQLite. Pour plus +de d\'etails consultez le +\ilink{document sur la conception des Services Catalogue +}{_ChapterStart30}. + +Les RPMs pour MySQL et PostgreSQL font partie de la distribution Red Hat. +Sinon, il est tout \`a fait ais\'e de les construire \`a partir des sources. +Consultez le chapitre +\ilink{ Installer et configurer MySQL}{_ChapterStart} ou +\ilink{ Installer et configurer PostgreSQL}{_ChapterStart10} de +ce document pour plus de d\'etails. Pour plus d'informations sur MySQL et +PostgreSQL, consultez +\elink{www.mysql.com}{http://www.mysql.com} ou +\elink{www.postgresql.org}{http://www.postgresql.org}. + +Configurer et construire SQLite est encore plus facile. Pour les d\'etails de +configuration de SQLite, consultez le chapitre +\ilink{Installer et Configurer SQLite}{_ChapterStart33} de ce +document. +\item + \label{MonDef} + Le service {\bf Bacula Monitor} est le programme qui permet \`a +l'administrateur ou \`a l'utilisateur de contr\^oler le statut des {\it +daemons} Bacula ({\bf Bacula Directors}, {\bf Bacula File Daemons} et {\bf +Bacula Storage Daemons}) (voir ci-dessus). Actuellement, la seule version +disponible est une version GTK+, qui fonctionne avec Gnome et KDE (ainsi que +tout gestionnaire de fen\^etre qui respecte le standard system tray +FreeDesktop.org). +\end{itemize} + +Pour r\'ealiser avec succ\`es les op\'erations de sauvegarde et restauration, +les quatre services suivants doivent \^etre configur\'es et lanc\'es : le +Director Daemon, le File Daemon, le Storage Daemon et MySQL, PostgreSQL ou +SQLite. + +\section{Configuration de Bacula} +\index[general]{Configuration de Bacula } +\index[general]{Bacula!Configuration de } +\addcontentsline{toc}{section}{Configuration de Bacula} + +Pour que Bacula comprenne votre syst\`eme, quels clients vous voulez +sauvegarder et comment, vous devez cr\'eer un certain nombre de fichiers de +configuration. La suite brosse un tableau de ces op\'erations. + +\includegraphics{./bacula-objects.eps} + +\section{Conventions utilis\'ees dans ce document} +\index[general]{Conventions utilis\'ees dans ce document } +\index[general]{Document!Conventions utilis\'ees dans ce } +\addcontentsline{toc}{section}{Conventions utilis\'ees dans ce document} + +{\bf Bacula} est en constante \'evolution, par cons\'equent, ce manuel ne sera +pas toujours en accord avec le code. Si un objet de ce manuel est +pr\'ec\'ed\'e d'un ast\'erisque (*), cela signifie que cette fonctionnalit\'e +particuli\`ere n'est pas impl\'ement\'ee. S'il est pr\'ec\'ed\'e d'un signe +plus (+), cela indique que la fonction est peut-\^etre partiellement +impl\'ement\'ee. + +Si vous lisez la version de ce manuel fournie avec les sources de Bacula, le +paragraphe ci-dessus reste vrai. En revanche, si vous lisez la version en +ligne : +\elink{www.bacula.org/manual}{http://www.bacula.org/manual}, veuillez garder +\`a l'esprit que cette version d\'ecrit la version courante de d\'eveloppement +de Bacula (celle du CVS) qui peut contenir des fonctionnalit\'es qui +n'existent pas dans la version "officielle". De m\^eme, il est +g\'en\'eralement un peu \`a la tra{\^\i}ne derri\`ere le code. + +\section{D\'emarrage rapide} +\index[general]{D\'emarrage rapide } +\index[general]{Rapide!D\'emarrage } +\addcontentsline{toc}{section}{D\'emarrage rapide} + +Pour faire fonctionner Bacula rapidement, nous vous recommandons de commencer +par parcourir la section Terminologie ci-dessous, de passer rapidement en +revue le chapitre suivant intitul\'e +\ilink{L'\'etat actuel de Bacula}{_ChapterStart2}, puis le +\ilink{Guide de d\'emarrage rapide de Bacula}{_ChapterStart37}, +qui vous donnera une vue d'ensemble de la mise en oeuvre de Bacula . Apr\`es +quoi vous devriez poursuivre avec le chapitre sur +\ilink{ L'installation de Bacula}{_ChapterStart17}, puis le chapitre +\ilink{Comment configurer Bacula}{_ChapterStart16}, et finalement, +le chapitre \ilink{Ex\'ecuter Bacula}{_ChapterStart1}. + +\section{Terminologie} +\index[general]{Terminologie } +\addcontentsline{toc}{section}{Terminologie} + +Pour faciliter la communication autour de ce projet, nous fournissons ici les +d\'efinitions de la terminologie que nous utilisons. + +\begin{description} + +\item [Administrateur] + \index[sd]{Administrateur } + La ou les personne(s) responsable(s) de l'administration du syst\`eme Bacula. + + +\item [Sauvegarde] + \index[sd]{Sauvegarde } + Nous utilisons ce terme pour un job Bacula qui sauvegarde des fichiers. + +\item [Fichier Bootstrap (Bootstrap File)] + \index[sd]{Fichier Bootstrap (Bootstrap File) } + Le bootstrap est un fichier ASCII qui contient, sous une forme compacte, les +commandes qui permettent \`a Bacula ou \`a l'utilitaire autonome {\bf +bextract} de restaurer les contenus d'un ou plusieurs volumes, par exemple, +l'\'etat courant d'un syst\`eme qui vient d'\^etre sauvegard\'e. Avec un +fichier bootstrap, Bacula peut restaurer votre syst\`eme sans catalogue. Vous +pouvez cr\'eer un fichier bootstrap depuis un catalogue pour extraire le +fichier que vous voulez. + +\item [Catalogue] + \index[sd]{Catalogue } + Le catalogue est utilis\'e pour stocker des informations sommaires concernant +les Jobs et Clients, les fichiers qui ont \'et\'e sauvegard\'es ainsi que le +ou les volume(s) o\`u ils ont \'et\'e sauvegard\'es. L'information stock\'ee +dans le catalogue permet \`a l'administrateur ou aux utilisateurs de +d\'eterminer quels jobs ont \'et\'e ex\'ecut\'es, leur statut, ainsi que +d'importantes caract\'eristiques de chaque fichier sauvegard\'e. Le catalogue +est une ressource en ligne, mais ne contient pas les donn\'ees pour les +fichiers sauvegard\'es. La plupart des informations stock\'ees dans le +catalogue le sont aussi sur les volumes de sauvegarde (i.e. cartouches). Bien +sur, les cartouches auront aussi une copie du fichier en plus de ses attributs + (voir ci-dessus). + +La fonction Catalogue est de celles qui distinguent Bacula de simples +programmes de sauvegarde et archivage tels que {\bf dump} et {\bf tar}. + +\item [Client] + \index[sd]{Client } + Dans la terminologie de Bacula, le mot Client d\'esigne une machine +sauvegard\'ee, et est synonyme de File service ou File Daemon. Nous nous y +r\'ef\'erons assez souvent par "le FD". Un client est d\'efini dans une +ressource de fichier de configuration. + +\item [Console] + \index[sd]{Console } + Le programme qui interface le Director, permettant \`a l'administrateur de +contr\^oler Bacula. + +\item [Daemon] + \index[sd]{Daemon } + Terminologie Unix pour un programme toujours pr\'esent en arri\`ere plan pour +prendre en charge une t\^ache donn\'ee. Sur les syst\`emes Windows, ainsi que +certains Linux, les {\it daemons} sont appel\'es {\bf Services}. + +\item [Directive] + \index[sd]{Directive } + Le terme directive est utilis\'e pour d\'esigner une entr\'ee ou +enregistrement \`a l'int\'erieur d'une ressource dans un fichier de +configuration qui d\'efinit un \'el\'ement sp\'ecifique. Par exemple, la +directive {\bf Name} d\'efinit le nom de la ressource. + +\item [Director] + \index[sd]{Director } + Le principal {\it daemon} serveur de Bacula qui planifie et dirige toutes +les op\'erations de Bacula. Occasionnellement, nous le d\'esignons par "le +DIR". + +\item [Differentielle (Differential)] + \index[sd]{Differentielle (Differential) } + Une sauvegarde qui inclut tous les fichiers modifi\'es depuis le lancement de +la derni\`ere sauvegarde compl\`ete (Full). Notez que d'autres logiciels de +sauvegarde peuvent d\'efinir ceci diff\'eremment. + +\item [Attributs de fichiers] + \index[sd]{Attributs de fichiers } + Les Attributs de fichiers sont toutes les informations n\'ecessaires au sujet +d'un fichier pour l'identifier, et toutes ses propri\'et\'es telles taille, +date de cr\'eation, date de modification, permission, etc. En principe, les +attributs sont int\'egralement manipul\'es par Bacula de sorte que +l'utilisateur n'a jamais \`a s'en pr\'eoccuper. Les attributs n'incluent pas +les donn\'ees du fichier. + +\item [File Daemon] + \index[sd]{File Daemon } + Le {\it daemon} ex\'ecut\'e sur l'ordinateur client \`a sauvegarder. Il est +aussi d\'esign\'e par Service Fichier (File Service) et parfois Service Client +ou FD. + +\item [ + \label{FileSetDef} + FileSet] +\index[sd]{a name } +Un FileSet est une ressource d'un fichier de configuration qui d\'efinit les +fichiers \`a sauvegarder. Il consiste en une liste de fichiers ou +r\'epertoires inclus, une liste de fichiers ou r\'epertoires exclus et la +fa\c{c}on dont les fichiers seront stock\'es (compression, chiffrement, +signatures). Pour plus de d\'etails consultez le paragraphe +\ilink{D\'efinition de la Ressource FileSet}{FileSetResource} +dans le chapitre Director de ce document. + +\item [Incrementale] + \index[sd]{Incrementale } + Une sauvegarde qui inclut tous les fichiers modifi\'es depuis le lancement de +la derni\`ere sauvegarde compl\`ete (Full), diff\'erentielle, ou +incr\'ementale. Normalement sp\'ecifi\'e dans la directive {\bf Level} +(niveau) dans la d\'efinition de la ressource Job, ou dans une ressource +Schedule. + +\item [ + \label{JobDef} + Job] +\index[sd]{a name } +Un Job Bacula est une ressource de configuration qui d\'efinit le travail que +Bacula doit effectuer pour sauvegarder ou restaurer un client particulier. Un +Job consiste en un {\bf Type}, (Type : backup, restore, verify, etc.), un +{\bf Niveau} (Level : full, incremental, ...), un {\bf FileSet}, et un lieu de +{\bf Stockage} o\`u \'ecrire les fichiers (Storage device, Media Pool). Pour +plus de d\'etails consultez le chapitre +\ilink{D\'efinition des Ressources Job}{JobResource} de ce +document. + +\item [Monitor] + \index[sd]{Monitor } + Le programme qui s'interface avec chacun des {\it daemons} pour permettre \`a +l'utilisateur ou \`a l'administrateur de surveiller le statut de Bacula. + +\item [Resource] + \index[sd]{Resource } + Une ressource est une partie d'un fichier de configuration qui d\'efinit une +unit\'e sp\'ecifique d'information disponible pour Bacula. Par exemple, la +ressource {\bf Job} d\'efinit toutes les propri\'et\'es d'un Job sp\'ecifique +: nom, schedule (planification), volume pool, type de sauvegarde, niveau de +sauvegarde, etc. + +\item [Restore] + \index[sd]{Restore } + Une Restore est une ressource de configuration qui d\'ecrit l'op\'eration de +restauration d'un fichier (perdu ou endommag\'e) depuis un medium de +sauvegarde. C'est l'op\'eration r\'eciproque d'une sauvegarde, sauf que, dans +la plupart des cas, une restauration concernera un petit ensemble de fichiers +tandis qu'une sauvegarde concerne le plus souvent l'ensemble des fichiers +d'un syst\`eme. Bien sur, apr\`es une d\'efaillance de disque(s), Bacula peut +\^etre appel\'e \`a effectuer une restauration compl\`ete de tous les +fichiers qui \'etaient sur le syst\`eme. + +\item [Schedule] + \index[sd]{Schedule } + Un Schedule est une ressource de configuration qui d\'efinit le moment de +l'ex\'ecution du Job Bacula. Pour utiliser un schedule, la ressource Job se +r\'ef\`ere au nom du Schedule. Pour plus de d\'etails, consultez la +\ilink{D\'efinition de la ressource Schedule}{ScheduleResource} +dans le chapitre Director de ce document. + +\item [Service] + \index[sd]{Service } + Terminologie Windows pour d\'esigner un {\it daemon} -- Voir plus haut. Elle +est maintenant fr\'equemment utilis\'ee dans les environnements Unix aussi. + +\item [Adresses de stockage] + \index[sd]{Adresses de stockage } + Les informations retourn\'ees par les Storage services qui localisent de +fa\c{c}on unique les fichiers sur un medium de sauvegarde. Elles consistent +en deux parties : l'une appartient \`a chaque fichier sauvegard\'e, l'autre +\`a l'ensemble du Job. Normalement, cette information est sauvegard\'ee dans +le catalogue de sorte que l'utilisateur n'a pas besoin de connaissances +particuli\`eres des adresses de stockage. L'adresse de stockage inclut les +attributs de fichiers (voir plus haut) ainsi que la localisation unique de +l'information sur le volume de sauvegarde. + +\item [Storage Daemon] + \index[sd]{Storage Daemon } + Le Storage Daemon, parfois d\'esign\'e par "SD" est le programme qui +\'ecrit les attributs et les donn\'ees sur un Volume de Stockage (Storage +Volume) (Usuellement une cartouche ou un disque). + +\item [Session] + \index[sd]{Session } + D\'esigne en principe le dialogue interne entre le File Daemon et le Storage +Daemon. Le File Daemon ouvre une {\bf session} avec le Storage Daemon pour +sauvegarder un Fileset, ou pour le restaurer. Une session est associ\'ee \`a +un et un seul Job Bacula (voir plus haut). + +\item [Verify] + \index[sd]{Verify } + Il s'agit d'un job qui compare les attributs du fichier actuel aux attributs +qui ont \'et\'e pr\'ealablement stock\'es dans le catalogue Bacula. Cette +fonction peut \^etre utilis\'ee pour d\'etecter les modifications de +syst\`emes de fichiers critiques, \`a la fa\c{c}on de {\bf Tripwire}. L'un +des avantages majeurs de l'utilisation de Bacula pour cette t\^ache est que +sur la machine que vous voulez prot\'eger, vous pouvez n'ex\'ecuter que le +File Daemon. Le Director, le Storage Daemon et le catalogue peuvent r\'esider +sur une autre machine. Par cons\'equent si votre serveur est un jour +compromis, il est peu probable que la base de donn\'ees de v\'erification ait +\'et\'e trifouill\'ee. + +Verify peut aussi \^etre utilis\'e pour s'assurer que les donn\'ees les plus +r\'ecemment \'ecrites sur un volume sont coh\'erentes avec ce qui figure dans +le catalogue (c-\`a-d il compare les attributs de fichiers), ou encore, +confronter le contenu du volume aux fichiers originaux sur le disque. + +\item [*Archive] + \index[sd]{*Archive } + Une op\'eration d'archivage est effectu\'ee apr\`es une sauvegarde, et +consiste en l'exclusion des volumes sur lesquels les donn\'ees sont +sauvegard\'ees de l'utilisation courante. Ces volumes sont marqu\'es +"Archived", et ne sont plus utilis\'es pour sauvegarder des fichiers. Tous +les fichiers contenus sur un Volume Archive sont supprim\'es du catalogue. +PAS ENCORE IMPLEMENTE. + +\item [*Update] + \index[sd]{*Update } + Une op\'eration Update synchronise les fichiers du syst\`eme distant sur ceux +du local. Ceci est l'\'equivalent d'une fonctionnalit\'e {\bf rdist}. PAS +ENCORE IMPLEMENTE. + +\item [P\'eriode de r\'etention] + \index[sd]{P\'eriode de r\'etention } + Bacula reconnait plusieurs sortes de p\'eriodes de r\'etention. Les plus +importantes sont la p\'eriode de r\'etention des fichiers, la p\'eriode de +r\'etention des jobs et la p\'eriode de r\'etention des volumes. Chacune de +ces p\'eriodes de r\'etention d\'esigne la dur\'ee pendant laquelle +l'enregistrement sp\'ecifique sera conserv\'e dans le catalogue. Ceci ne doit +pas \^etre confondu avec le temps pendant lequel les donn\'ees sauvegard\'ees +sur un volume sont valides. + +La p\'eriode de r\'etention des fichiers d\'etermine la dur\'ee pendant +laquelle les enregistrements concernant les fichiers seront gard\'es dans le +catalogue. Cette p\'eriode est importante car le volume des enregistrements +relatifs aux fichiers occupe, de loin, le plus d'espace dans la base de +donn\'ees. Par cons\'equent, vous devez vous assurer qu'un "\'elagage" +(NDT : pruning) r\'egulier de ces enregistrements est effectu\'e. (Voir la +commande {\bf retention} de la Console pour plus de d\'etails sur ce sujet). + +La p\'eriode de r\'etention des jobs est la dur\'ee pendant laquelle les +enregistrements relatifs aux jobs seront conserv\'es dans le catalogue. Notez +que tous les enregistrements relatifs aux fichiers sont attach\'es aux jobs +qui ont sauvegard\'e ces fichiers. Les enregistrements relatifs aux fichiers +peuvent \^etre purg\'es tout en conservant ceux relatifs aux jobs. Dans ce +cas, l'information concernant les jobs ex\'ecut\'es restera disponible, mais +pas les d\'etails des fichiers sauvegard\'es. Normalement, lorsqu'un job est +purg\'e, tous les enregistrements concernant les fichiers qu'il a +sauvegard\'e le sont aussi. + +La p\'eriode de r\'etention des volumes est la +dur\'ee minimale de conservation d'un volume avant qu'il ne soit +r\'eutilis\'e. Bacula n'effacera, en principe, jamais un volume qui contient +la seule copie de sauvegarde d'un fichier. Dans les conditions id\'eales, le +catalogue maintiendrait les entr\'ees pour tous les fichiers sauvegard\'es +pour tous les volumes courants. Une fois qu'un volume est \'ecras\'e, les +fichiers qui \'etaient sauvegard\'es dessus sont automatiquement effac\'es du +catalogue. Cependant, s'il y a un tr\`es gros pool de volumes ou si un volume +n'est jamais \'ecras\'e, le catalogue pourrait devenir \'enorme. Pour +maintenir le catalogue dans des proportions g\'erables, les informations de +sauvegarde devraient \^etre supprim\'ees apr\`es une p\'eriode de r\'etention +des fichiers d\'efinie. + +\item [Scan] + \index[sd]{Scan } + Une op\'eration de scan consiste en un balayage du contenu d'un volume ou +d'une s\'erie de volumes. Ces volumes et les informations concernant les +fichiers qu'ils contiennent sont restaur\'es vers le catalogue Bacula. Une +fois ces informations restaur\'ees, les fichiers sauvegard\'es sur ces +volumes pourront \^etre ais\'ement restaur\'es. Cette fonction est +particuli\`erement utile si certains volumes ou jobs ont d\'epass\'e leur +p\'eriode de r\'etention et ont \'et\'e \'elagu\'es ou purg\'es du +catalogue. Le balayage des donn\'ees des volumes est effectu\'e en utilisant +le programme {\bf bscan}. Consultez la +\ilink{section bscan }{bscan} du chapitre sur les utilitaires +Bacula de ce manuel pour plus de d\'etails. + +\item [Volume] + \index[sd]{Volume } + Un volume est une unit\'e d'archivage, usuellement une cartouche ou un +fichier nomm\'e sur disque o\`u Bacula stocke les donn\'ees pour un ou +plusieurs jobs de sauvegarde. Tous les volumes Bacula ont un label unique +(logiciel) \'ecrit sur le volume par Bacula afin qu'il puisse \^etre assur\'e de +lire le bon volume. (En principe, il ne devrait pas y avoir de +confusion avec des fichiers disques, mais avec des cartouches, il est facile +de monter la mauvaise). +\end{description} + +\section{Ce que Bacula n'est pas} +\index[general]{Ce que Bacula n'est pas } +\index[general]{Pas!Ce que Bacula n'est } +\addcontentsline{toc}{section}{Ce que Bacula n'est pas} + +{\bf Bacula} est un programme de sauvegarde, restauration et v\'erification, +ce n'est pas un syst\`eme complet de disaster recovery +\label{c} +\`a lui seul, mais il peut en \^etre une partie clef si vous planifiez +soigneusement et suivez les instructions incluses dans le chapitre +\ilink{ Plan de reprise d'activit\'e avec Bacula}{_ChapterStart38} de +ce manuel. + +Avec la planification appropri\'ee, telle que d\'ecrite dans le chapitre sur le +plan de reprise d'activit\'e, {\bf Bacula} peut devenir la pi\`ece centrale de +votre plan de reprise d'activit\'e. Par exemple, si vous avez cr\'e\'e un(e) +disque(tte) boot d'urgence et un(e) disque(tte) de secours Bacula pour +sauvegarder les informations de partitionnement courantes de votre disque dur, +et maintenu un jeu de sauvegardes complet de votre syst\`eme, il est possible +de reconstruire compl\`etement votre syst\`eme "depuis le m\'etal brut" +(NDT : From bare metal) +\label{d1} +. + +Si vous avez utilis\'e la directive {\bf WriteBootstrap} dans votre job ou +quelque autre moyen pour sauvegarder un fichier bootstrap valide, vous pourrez +l'utiliser pour extraire les fichiers n\'ecessaires (sans utiliser le +catalogue et sans chercher manuellement les fichiers \`a restaurer). + +\section{Interactions entre les services Bacula} +\index[general]{Bacula!Interactions entre les services } +\index[general]{Interactions entre les services Bacula } +\addcontentsline{toc}{section}{Interactions entre les services Bacula} + +Le diagramme fonctionnel suivant montre les interactions typiques entre les +services Bacula pour un job de type sauvegarde. Chaque bloc repr\'esente en +g\'en\'eral un processus s\'epar\'e (normalement un {\it daemon}). En +g\'en\'eral, le director surveille le flux d'informations. Il maintient aussi +le catalogue. \includegraphics{./flow.eps} diff --git a/docs/manuals/fr/concepts/gpl.tex b/docs/manuals/fr/concepts/gpl.tex new file mode 100644 index 00000000..a368afc7 --- /dev/null +++ b/docs/manuals/fr/concepts/gpl.tex @@ -0,0 +1,420 @@ +%% +%% + +\section*{GNU General Public License} +\label{GplChapter} +\index[general]{GNU General Public License } +\index[general]{License!GNU General Public } + +\elink{image of a Philosophical +GNU}{http://www.gnu.org/graphics/philosophicalgnu.html} + +\begin{itemize} +\item + \elink{What to do if you see a possible GPL + violation}{http://www.gnu.org/copyleft/gpl-violation.html} +\item + \elink{Translations of the + GPL}{http://www.gnu.org/copyleft/copyleft.html\#translations} +\end{itemize} + + +\section{Table of Contents} +\index[general]{Table of Contents } +\index[general]{Contents!Table of } + +\begin{itemize} +\item + \label{TOC1} + \ilink{GNU GENERAL PUBLIC LICENSE}{SEC1} + +\begin{itemize} +\item + \label{TOC2} + \ilink{Preamble}{SEC2} +\item + \label{TOC3} + \ilink{TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND +MODIFICATION}{SEC3} +\item + \label{TOC4} + \ilink{How to Apply These Terms to Your New Programs}{SEC4} +\end{itemize} + +\end{itemize} + + +\section{GNU GENERAL PUBLIC LICENSE} +\label{SEC1} +\index[general]{GNU GENERAL PUBLIC LICENSE } +\index[general]{LICENSE!GNU GENERAL PUBLIC } + +Version 2, June 1991 + +\footnotesize +\begin{verbatim} +Copyright (C) 1989, 1991 Free Software Foundation, Inc. +51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +\end{verbatim} +\normalsize + +\section{Preamble} +\label{SEC2} +\index[general]{Preamble } + +The licenses for most software are designed to take away your freedom to share +and change it. By contrast, the GNU General Public License is intended to +guarantee your freedom to share and change free software\verb:--:to make sure the +software is free for all its users. This General Public License applies to +most of the Free Software Foundation's software and to any other program whose +authors commit to using it. (Some other Free Software Foundation software is +covered by the GNU Library General Public License instead.) You can apply it +to your programs, too. + +When we speak of free software, we are referring to freedom, not price. Our +General Public Licenses are designed to make sure that you have the freedom to +distribute copies of free software (and charge for this service if you wish), +that you receive source code or can get it if you want it, that you can change +the software or use pieces of it in new free programs; and that you know you +can do these things. + +To protect your rights, we need to make restrictions that forbid anyone to +deny you these rights or to ask you to surrender the rights. These +restrictions translate to certain responsibilities for you if you distribute +copies of the software, or if you modify it. + +For example, if you distribute copies of such a program, whether gratis or for +a fee, you must give the recipients all the rights that you have. You must +make sure that they, too, receive or can get the source code. And you must +show them these terms so they know their rights. + +We protect your rights with two steps: (1) copyright the software, and (2) +offer you this license which gives you legal permission to copy, distribute +and/or modify the software. + +Also, for each author's protection and ours, we want to make certain that +everyone understands that there is no warranty for this free software. If the +software is modified by someone else and passed on, we want its recipients to +know that what they have is not the original, so that any problems introduced +by others will not reflect on the original authors' reputations. + +Finally, any free program is threatened constantly by software patents. We +wish to avoid the danger that redistributors of a free program will +individually obtain patent licenses, in effect making the program proprietary. +To prevent this, we have made it clear that any patent must be licensed for +everyone's free use or not licensed at all. + +The precise terms and conditions for copying, distribution and modification +follow. + +\section{TERMS AND CONDITIONS} +\label{SEC3} +\index[general]{CONDITIONS!TERMS AND } +\index[general]{TERMS AND CONDITIONS } + +TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + +{\bf 0.} This License applies to any program or other work which contains a +notice placed by the copyright holder saying it may be distributed under the +terms of this General Public License. The "Program", below, refers to any +such program or work, and a "work based on the Program" means either the +Program or any derivative work under copyright law: that is to say, a work +containing the Program or a portion of it, either verbatim or with +modifications and/or translated into another language. (Hereinafter, +translation is included without limitation in the term "modification".) Each +licensee is addressed as "you". + +Activities other than copying, distribution and modification are not covered +by this License; they are outside its scope. The act of running the Program is +not restricted, and the output from the Program is covered only if its +contents constitute a work based on the Program (independent of having been +made by running the Program). Whether that is true depends on what the Program +does. + +{\bf 1.} You may copy and distribute verbatim copies of the Program's source +code as you receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice and +disclaimer of warranty; keep intact all the notices that refer to this License +and to the absence of any warranty; and give any other recipients of the +Program a copy of this License along with the Program. + +You may charge a fee for the physical act of transferring a copy, and you may +at your option offer warranty protection in exchange for a fee. + +{\bf 2.} You may modify your copy or copies of the Program or any portion of +it, thus forming a work based on the Program, and copy and distribute such +modifications or work under the terms of Section 1 above, provided that you +also meet all of these conditions: + +\begin{itemize} +\item {\bf a)} You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + +\item {\bf b)} You must cause any work that you distribute or publish, that + in whole or in part contains or is derived from the Program or any part + thereof, to be licensed as a whole at no charge to all third parties under + the terms of this License. + +\item {\bf c)} If the modified program normally reads commands interactively + when run, you must cause it, when started running for such interactive use in + the most ordinary way, to print or display an announcement including an + appropriate copyright notice and a notice that there is no warranty (or else, + saying that you provide a warranty) and that users may redistribute the + program under these conditions, and telling the user how to view a copy of + this License. (Exception: if the Program itself is interactive but does not + normally print such an announcement, your work based on the Program is not + required to print an announcement.) +\end{itemize} + +These requirements apply to the modified work as a whole. If identifiable +sections of that work are not derived from the Program, and can be reasonably +considered independent and separate works in themselves, then this License, +and its terms, do not apply to those sections when you distribute them as +separate works. But when you distribute the same sections as part of a whole +which is a work based on the Program, the distribution of the whole must be on +the terms of this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest your +rights to work written entirely by you; rather, the intent is to exercise the +right to control the distribution of derivative or collective works based on +the Program. + +In addition, mere aggregation of another work not based on the Program with +the Program (or with a work based on the Program) on a volume of a storage or +distribution medium does not bring the other work under the scope of this +License. + +{\bf 3.} You may copy and distribute the Program (or a work based on it, under +Section 2) in object code or executable form under the terms of Sections 1 and +2 above provided that you also do one of the following: + +\begin{itemize} +\item {\bf a)} Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections 1 and 2 + above on a medium customarily used for software interchange; or, + +\item {\bf b)} Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your cost of + physically performing source distribution, a complete machine-readable copy of + the corresponding source code, to be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + +\item {\bf c)} Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is allowed only + for noncommercial distribution and only if you received the program in object + code or executable form with such an offer, in accord with Subsection b + above.) +\end{itemize} + +The source code for a work means the preferred form of the work for making +modifications to it. For an executable work, complete source code means all +the source code for all modules it contains, plus any associated interface +definition files, plus the scripts used to control compilation and +installation of the executable. However, as a special exception, the source +code distributed need not include anything that is normally distributed (in +either source or binary form) with the major components (compiler, kernel, and +so on) of the operating system on which the executable runs, unless that +component itself accompanies the executable. + +If distribution of executable or object code is made by offering access to +copy from a designated place, then offering equivalent access to copy the +source code from the same place counts as distribution of the source code, +even though third parties are not compelled to copy the source along with the +object code. + +{\bf 4.} You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt otherwise to +copy, modify, sublicense or distribute the Program is void, and will +automatically terminate your rights under this License. However, parties who +have received copies, or rights, from you under this License will not have +their licenses terminated so long as such parties remain in full compliance. + +{\bf 5.} You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or distribute +the Program or its derivative works. These actions are prohibited by law if +you do not accept this License. Therefore, by modifying or distributing the +Program (or any work based on the Program), you indicate your acceptance of +this License to do so, and all its terms and conditions for copying, +distributing or modifying the Program or works based on it. + +{\bf 6.} Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the original +licensor to copy, distribute or modify the Program subject to these terms and +conditions. You may not impose any further restrictions on the recipients' +exercise of the rights granted herein. You are not responsible for enforcing +compliance by third parties to this License. + +{\bf 7.} If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or otherwise) +that contradict the conditions of this License, they do not excuse you from +the conditions of this License. If you cannot distribute so as to satisfy +simultaneously your obligations under this License and any other pertinent +obligations, then as a consequence you may not distribute the Program at all. +For example, if a patent license would not permit royalty-free redistribution +of the Program by all those who receive copies directly or indirectly through +you, then the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply and +the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any patents or +other property right claims or to contest validity of any such claims; this +section has the sole purpose of protecting the integrity of the free software +distribution system, which is implemented by public license practices. Many +people have made generous contributions to the wide range of software +distributed through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing to +distribute software through any other system and a licensee cannot impose that +choice. + +This section is intended to make thoroughly clear what is believed to be a +consequence of the rest of this License. + +{\bf 8.} If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the original +copyright holder who places the Program under this License may add an explicit +geographical distribution limitation excluding those countries, so that +distribution is permitted only in or among countries not thus excluded. In +such case, this License incorporates the limitation as if written in the body +of this License. + +{\bf 9.} The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will be +similar in spirit to the present version, but may differ in detail to address +new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any later +version", you have the option of following the terms and conditions either of +that version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of this License, +you may choose any version ever published by the Free Software Foundation. + +{\bf 10.} If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author to +ask for permission. For software which is copyrighted by the Free Software +Foundation, write to the Free Software Foundation; we sometimes make +exceptions for this. Our decision will be guided by the two goals of +preserving the free status of all derivatives of our free software and of +promoting the sharing and reuse of software generally. + +{\bf NO WARRANTY} + +{\bf 11.} BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE +THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR +IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO +THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM +PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION. + +{\bf 12.} IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO +LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR +THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + +END OF TERMS AND CONDITIONS + +\section{How to Apply These Terms to Your New Programs} +\label{SEC4} +\index[general]{Programs!How to Apply These Terms to Your New } +\index[general]{How to Apply These Terms to Your New Programs } + +If you develop a new program, and you want it to be of the greatest possible +use to the public, the best way to achieve this is to make it free software +which everyone can redistribute and change under these terms. + +To do so, attach the following notices to the program. It is safest to attach +them to the start of each source file to most effectively convey the exclusion +of warranty; and each file should have at least the "copyright" line and a +pointer to where the full notice is found. + +\footnotesize +\begin{verbatim} +{\em one line to give the program's name and an idea of what it does.} +Copyright (C) {\em yyyy} {\em name of author} +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA +02110-1301 USA +\end{verbatim} +\normalsize + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this when it +starts in an interactive mode: + +\footnotesize +\begin{verbatim} +Gnomovision version 69, Copyright (C) {\em year} {\em name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. This is free software, and you are welcome +to redistribute it under certain conditions; type `show c' +for details. +\end{verbatim} +\normalsize + +The hypothetical commands {\tt `show w'} and {\tt `show c'} should show the +appropriate parts of the General Public License. Of course, the commands you +use may be called something other than {\tt `show w'} and {\tt `show c'}; they +could even be mouse-clicks or menu items\verb:--:whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + +\footnotesize +\begin{verbatim} +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. +{\em signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +\end{verbatim} +\normalsize + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General Public +License instead of this License. +Return to +\elink{GNU's home page}{http://www.gnu.org/home.html}. + +FSF \& GNU inquiries \& questions to +\elink{gnu@gnu.org}{mailto:gnu@gnu.org}. Other +\elink{ways to contact}{http://www.gnu.org/home.html\#ContactInfo} the FSF. + +Comments on these web pages to +\elink{webmasters@www.gnu.org}{mailto:webmasters@www.gnu.org}, send other +questions to +\elink{gnu@gnu.org}{mailto:gnu@gnu.org}. + +Copyright notice above. +Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, +Boston, MA 02110-1301 USA + +Updated: 3 Jan 2000 rms diff --git a/docs/manuals/fr/concepts/index.perl b/docs/manuals/fr/concepts/index.perl new file mode 100644 index 00000000..bc4e1b60 --- /dev/null +++ b/docs/manuals/fr/concepts/index.perl @@ -0,0 +1,564 @@ +# This module does multiple indices, supporting the style of the LaTex 'index' +# package. + +# Version Information: +# 16-Feb-2005 -- Original Creation. Karl E. Cunningham +# 14-Mar-2005 -- Clarified and Consolodated some of the code. +# Changed to smoothly handle single and multiple indices. + +# Two LaTeX index formats are supported... +# --- SINGLE INDEX --- +# \usepackage{makeidx} +# \makeindex +# \index{entry1} +# \index{entry2} +# \index{entry3} +# ... +# \printindex +# +# --- MULTIPLE INDICES --- +# +# \usepackage{makeidx} +# \usepackage{index} +# \makeindex -- latex2html doesn't care but LaTeX does. +# \newindex{ref1}{ext1}{ext2}{title1} +# \newindex{ref2}{ext1}{ext2}{title2} +# \newindex{ref3}{ext1}{ext2}{title3} +# \index[ref1]{entry1} +# \index[ref1]{entry2} +# \index[ref3]{entry3} +# \index[ref2]{entry4} +# \index{entry5} +# \index[ref3]{entry6} +# ... +# \printindex[ref1] +# \printindex[ref2] +# \printindex[ref3] +# \printindex +# ___________________ +# +# For the multiple-index style, each index is identified by the ref argument to \newindex, \index, +# and \printindex. A default index is allowed, which is indicated by omitting the optional +# argument. The default index does not require a \newindex command. As \index commands +# are encountered, their entries are stored according +# to the ref argument. When the \printindex command is encountered, the stored index +# entries for that argument are retrieved and printed. The title for each index is taken +# from the last argument in the \newindex command. +# While processing \index and \printindex commands, if no argument is given the index entries +# are built into a default index. The title of the default index is simply "Index". +# This makes the difference between single- and multiple-index processing trivial. +# +# Another method can be used by omitting the \printindex command and just using \include to +# pull in index files created by the makeindex program. These files will start with +# \begin{theindex}. This command is used to determine where to print the index. Using this +# approach, the indices will be output in the same order as the newindex commands were +# originally found (see below). Using a combination of \printindex and \include{indexfile} has not +# been tested and may produce undesireable results. +# +# The index data are stored in a hash for later sorting and output. As \printindex +# commands are handled, the order in which they were found in the tex filea is saved, +# associated with the ref argument to \printindex. +# +# We use the original %index hash to store the index data into. We append a \002 followed by the +# name of the index to isolate the entries in different indices from each other. This is necessary +# so that different indices can have entries with the same name. For the default index, the \002 is +# appended without the name. +# +# Since the index order in the output cannot be determined if the \include{indexfile} +# command is used, the order will be assumed from the order in which the \newindex +# commands were originally seen in the TeX files. This order is saved as well as the +# order determined from any printindex{ref} commands. If \printindex commnads are used +# to specify the index output, that order will be used. If the \include{idxfile} command +# is used, the order of the original newindex commands will be used. In this case the +# default index will be printed last since it doesn't have a corresponding \newindex +# command and its order cannot be determined. Mixing \printindex and \include{idxfile} +# commands in the same file is likely to produce less than satisfactory results. +# +# +# The hash containing index data is named %indices. It contains the following data: +#{ +# 'title' => { +# $ref1 => $indextitle , +# $ref2 => $indextitle , +# ... +# }, +# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +#} + + +# Globals to handle multiple indices. +my %indices; + +# This tells the system to use up to 7 words in index entries. +$WORDS_IN_INDEX = 10; + +# KEC 2-18-05 +# Handles the \newindex command. This is called if the \newindex command is +# encountered in the LaTex source. Gets the index ref and title from the arguments. +# Saves the index ref and title. +# Note that we are called once to handle multiple \newindex commands that are +# newline-separated. +sub do_cmd_newindex { + my $data = shift; + # The data is sent to us as fields delimited by their ID #'s. We extract the + # fields. + foreach my $line (split("\n",$data)) { + my @fields = split (/(?:\<\#\d+?\#\>)+/,$line); + + # The index name and title are the second and fourth fields in the data. + if ($line =~ /^ \001 + # @ -> \002 + # | -> \003 + $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines + # protect \001 occurring with images + $str =~ s/\001/\016/g; # 0x1 to 0xF + $str =~ s/\\\\/\011/g; # Double backslash -> 0xB + $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC + $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD + $str =~ s/!/\001/g; # Exclamation point -> 0x1 + $str =~ s/\013/!/g; # 0xD -> Exclaimation point + $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF + $str =~ s/@/\002/g; # At sign -> 0x2 + $str =~ s/\015/@/g; # 0xF to At sign + $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11 + $str =~ s/\|/\003/g; # Vertical line to 0x3 + $str =~ s/\017/|/g; # 0x11 to vertical line + $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is + $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot; + $str =~ s/\011/\\\\/g; # 0x11 to double backslash + local($key_part, $pageref) = split("\003", $str, 2); + + # For any keys of the form: blablabla!blablabla, which want to be split at the + # exclamation point, replace the ! with a comma and a space. We don't do it + # that way for this index. + $key_part =~ s/\001/, /g; + local(@keys) = split("\001", $key_part); + # If TITLE is not yet available use $before. + $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title))); + $TITLE = $before unless $TITLE; + # Save the reference + local($words) = ''; + if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; } + elsif ($SHORT_INDEX) { $words = &make_shortidxname; } + else { $words = &make_idxname; } + local($super_key) = ''; + local($sort_key, $printable_key, $cur_key); + foreach $key (@keys) { + $key =~ s/\016/\001/g; # revert protected \001s + ($sort_key, $printable_key) = split("\002", $key); + # + # RRM: 16 May 1996 + # any \label in the printable-key will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($printable_key =~ /tex2html_anchor_mark/ ) { + $printable_key =~ s/><\/A>$cross_ref_mark/ + $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_label = $external_labels{$label} unless + ($ref_label = $ref_files{$label}); + '"' . "$ref_label#$label" . '">' . + &get_ref_mark($label,$id)} + /geo; + } + $printable_key =~ s/<\#[^\#>]*\#>//go; + #RRM + # recognise \char combinations, for a \backslash + # + $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s + $printable_key =~ s/\&\#;\`
/\\/g; # ditto + $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto + # + # $sort_key .= "@$printable_key" if !($printable_key); # RRM + $sort_key .= "@$printable_key" if !($sort_key); # RRM + $sort_key =~ tr/A-Z/a-z/; + if ($super_key) { + $cur_key = $super_key . "\001" . $sort_key; + $sub_index{$super_key} .= $cur_key . "\004"; + } else { + $cur_key = $sort_key; + } + + # Append the $index_name to the current key with a \002 delimiter. This will + # allow the same index entry to appear in more than one index. + $index_key = $cur_key . "\002$index_name"; + + $index{$index_key} .= ""; + + # + # RRM, 15 June 1996 + # if there is no printable key, but one is known from + # a previous index-entry, then use it. + # + if (!($printable_key) && ($printable_key{$index_key})) + { $printable_key = $printable_key{$index_key}; } +# if (!($printable_key) && ($printable_key{$cur_key})) +# { $printable_key = $printable_key{$cur_key}; } + # + # do not overwrite the printable_key if it contains an anchor + # + if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ )) + { $printable_key{$index_key} = $printable_key || $key; } +# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ )) +# { $printable_key{$cur_key} = $printable_key || $key; } + + $super_key = $cur_key; + } + # + # RRM + # page-ranges, from |( and |) and |see + # + if ($pageref) { + if ($pageref eq "\(" ) { + $pageref = ''; + $next .= " from "; + } elsif ($pageref eq "\)" ) { + $pageref = ''; + local($next) = $index{$index_key}; +# local($next) = $index{$cur_key}; + # $next =~ s/[\|] *$//; + $next =~ s/(\n )?\| $//; + $index{$index_key} = "$next to "; +# $index{$cur_key} = "$next to "; + } + } + + if ($pageref) { + $pageref =~ s/\s*$//g; # remove trailing spaces + if (!$pageref) { $pageref = ' ' } + $pageref =~ s/see/see <\/i> /g; + # + # RRM: 27 Dec 1996 + # check if $pageref corresponds to a style command. + # If so, apply it to the $words. + # + local($tmp) = "do_cmd_$pageref"; + if (defined &$tmp) { + $words = &$tmp("<#0#>$words<#0#>"); + $words =~ s/<\#[^\#]*\#>//go; + $pageref = ''; + } + } + # + # RRM: 25 May 1996 + # any \label in the pageref section will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($pageref) { + if ($pageref =~ /tex2html_anchor_mark/ ) { + $pageref =~ s/><\/A>$cross_ref_mark/ + $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_files{$label} = ''; # ???? RRM + if ($index_labels{$label}) { $ref_label = ''; } + else { $ref_label = $external_labels{$label} + unless ($ref_label = $ref_files{$label}); + } + '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo; + } + $pageref =~ s/<\#[^\#>]*\#>//go; + + if ($pageref eq ' ') { $index{$index_key}='@'; } + else { $index{$index_key} .= $pageref . "\n | "; } + } else { + local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words); + $thisref =~ s/\n//g; + $index{$index_key} .= $thisref."\n | "; + } + #print "\nREF: $sort_key : $index_key :$index{$index_key}"; + + #join('',"$anchor_invisible_mark<\/A>",$_); + + "$anchor_invisible_mark<\/A>"; +} + + +# KEC. -- Copied from makeidx.perl, then modified to do multiple indices. +# Feeds the index entries to the output. This is called for each index to be built. +# +# Generates a list of lookup keys for index entries, from both %printable_keys +# and %index keys. +# Sorts the keys according to index-sorting rules. +# Removes keys with a 0x01 token. (duplicates?) +# Builds a string to go to the index file. +# Adds the index entries to the string if they belong in this index. +# Keeps track of which index is being worked on, so only the proper entries +# are included. +# Places the index just built in to the output at the proper place. +{ my $index_number = 0; +sub add_real_idx { + print "\nDoing the index ... Index Number $index_number\n"; + local($key, @keys, $next, $index, $old_key, $old_html); + my ($idx_ref,$keyref); + # RRM, 15.6.96: index constructed from %printable_key, not %index + @keys = keys %printable_key; + + while (/$idx_mark/) { + # Get the index reference from what follows the $idx_mark and + # remove it from the string. + s/$idxmark\002(.*?)\002/$idxmark/; + $idx_ref = $1; + $index = ''; + # include non- makeidx index-entries + foreach $key (keys %index) { + next if $printable_key{$key}; + $old_key = $key; + if ($key =~ s/###(.*)$//) { + next if $printable_key{$key}; + push (@keys, $key); + $printable_key{$key} = $key; + if ($index{$old_key} =~ /HREF="([^"]*)"/i) { + $old_html = $1; + $old_html =~ /$dd?([^#\Q$dd\E]*)#/; + $old_html = $1; + } else { $old_html = '' } + $index{$key} = $index{$old_key} . $old_html."\n | "; + }; + } + @keys = sort makeidx_keysort @keys; + @keys = grep(!/\001/, @keys); + my $cnt = 0; + foreach $key (@keys) { + my ($keyref) = $key =~ /.*\002(.*)/; + next unless ($idx_ref eq $keyref); # KEC. + $index .= &add_idx_key($key); + $cnt++; + } + print "$cnt Index Entries Added\n"; + $index = '
'.$index unless ($index =~ /^\s*/); + $index_number++; # KEC. + if ($SHORT_INDEX) { + print "(compact version with Legend)"; + local($num) = ( $index =~ s/\ 50 ) { + s/$idx_mark/$preindex
\n$index\n<\/DL>$preindex/o; + } else { + s/$idx_mark/$preindex
\n$index\n<\/DL>/o; + } + } else { + s/$idx_mark/
\n$index\n<\/DL>/o; } + } +} +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# The bibliography and the index should be treated as separate sections +# in their own HTML files. The \bibliography{} command acts as a sectioning command +# that has the desired effect. But when the bibliography is constructed +# manually using the thebibliography environment, or when using the +# theindex environment it is not possible to use the normal sectioning +# mechanism. This subroutine inserts a \bibliography{} or a dummy +# \textohtmlindex command just before the appropriate environments +# to force sectioning. +sub add_bbl_and_idx_dummy_commands { + local($id) = $global{'max_id'}; + + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg; + ## if ($bbl_cnt == 1) { + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo; + #} + $global{'max_id'} = $id; + # KEC. Modified to global substitution to place multiple index tokens. + s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go; + # KEC. Modified to pick up the optional argument to \printindex + s/[\\]printindex\s*(\[.*?\])?/ + do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego; + &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands); +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# For each textohtmlindex mark found, determine the index titles and headers. +# We place the index ref in the header so the proper index can be generated later. +# For the default index, the index ref is blank. +# +# One problem is that this routine is called twice.. Once for processing the +# command as originally seen, and once for processing the command when +# doing the name for the index file. We can detect that by looking at the +# id numbers (or ref) surrounding the \theindex command, and not incrementing +# index_number unless a new id (or ref) is seen. This has the side effect of +# having to unconventionally start the index_number at -1. But it works. +# +# Gets the title from the list of indices. +# If this is the first index, save the title in $first_idx_file. This is what's referenced +# in the navigation buttons. +# Increment the index_number for next time. +# If the indexname command is defined or a newcommand defined for indexname, do it. +# Save the index TITLE in the toc +# Save the first_idx_file into the idxfile. This goes into the nav buttons. +# Build index_labels if needed. +# Create the index headings and put them in the output stream. + +{ my $index_number = 0; # Will be incremented before use. + my $first_idx_file; # Static + my $no_increment = 0; + +sub do_cmd_textohtmlindex { + local($_) = @_; + my ($idxref,$idxnum,$index_name); + + # We get called from make_name with the first argument = "\001noincrement". This is a sign + # to not increment $index_number the next time we are called. We get called twice, once + # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name + # but doesn't use the result so we get called a second time by process_command. This works fine + # except for cases where there are multiple indices except if they aren't named, which is the case + # when the index is inserted by an include command in latex. In these cases we are only able to use + # the index number to decide which index to draw from, and we don't know how to increment that index + # number if we get called a variable number of times for the same index, as is the case between + # making html (one output file) and web (multiple output files) output formats. + if (/\001noincrement/) { + $no_increment = 1; + return; + } + + # Remove (but save) the index reference + s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e; + + # If we have an $idxref, the index name was specified. In this case, we have all the + # information we need to carry on. Otherwise, we need to get the idxref + # from the $index_number and set the name to "Index". + if ($idxref) { + $index_name = $indices{'title'}{$idxref}; + } else { + if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) { + $index_name = $indices{'title'}{$idxref}; + } else { + $idxref = ''; + $index_name = "Index"; + } + } + + $idx_title = "Index"; # The name displayed in the nav bar text. + + # Only set $idxfile if we are at the first index. This will point the + # navigation panel to the first index file rather than the last. + $first_idx_file = $CURRENT_FILE if ($index_number == 0); + $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar. + $toc_sec_title = $index_name; # Index link text in the toc. + $TITLE = $toc_sec_title; # Title for this index, from which its filename is built. + if (%index_labels) { &make_index_labels(); } + if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); } + else { $preindex = ''; } + local $idx_head = $section_headings{'textohtmlindex'}; + local($heading) = join('' + , &make_section_heading($TITLE, $idx_head) + , $idx_mark, "\002", $idxref, "\002" ); + local($pre,$post) = &minimize_open_tags($heading); + $index_number++ unless ($no_increment); + $no_increment = 0; + join('',"
\n" , $pre, $_); +} +} + +# Returns an index key, given the key passed as the first argument. +# Not modified for multiple indices. +sub add_idx_key { + local($key) = @_; + local($index, $next); + if (($index{$key} eq '@' )&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { $index .= "

\n
".&print_key."\n
"; } + else { $index .= "

\n
".&print_key."\n
"; } + } elsif (($index{$key})&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { + $next = "
".&print_key."\n : ". &print_idx_links; + } else { + $next = "
".&print_key."\n
". &print_idx_links; + } + $index .= $next."\n"; + $index_printed{$key} = 1; + } + + if ($sub_index{$key}) { + local($subkey, @subkeys, $subnext, $subindex); + @subkeys = sort(split("\004", $sub_index{$key})); + if ($SHORT_INDEX) { + $index .= "
".&print_key unless $index_printed{$key}; + $index .= "
\n"; + } else { + $index .= "
".&print_key."\n
" unless $index_printed{$key}; + $index .= "
\n"; + } + foreach $subkey (@subkeys) { + $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey}); + } + $index .= "
\n"; + } + return $index; +} + +1; # Must be present as the last line. diff --git a/docs/manuals/fr/concepts/latex2html-init.pl b/docs/manuals/fr/concepts/latex2html-init.pl new file mode 100644 index 00000000..14b5c319 --- /dev/null +++ b/docs/manuals/fr/concepts/latex2html-init.pl @@ -0,0 +1,10 @@ +# This file serves as a place to put initialization code and constants to +# affect the behavior of latex2html for generating the bacula manuals. + +# $LINKPOINT specifies what filename to use to link to when creating +# index.html. Not that this is a hard link. +$LINKPOINT='"$OVERALL_TITLE"'; + + +# The following must be the last line of this file. +1; diff --git a/docs/manuals/fr/concepts/lesser.tex b/docs/manuals/fr/concepts/lesser.tex new file mode 100644 index 00000000..6fcc81ed --- /dev/null +++ b/docs/manuals/fr/concepts/lesser.tex @@ -0,0 +1,573 @@ +%% +%% + +\section*{GNU Lesser General Public License} +\label{LesserChapter} +\index[general]{GNU Lesser General Public License } +\index[general]{License!GNU Lesser General Public } + +\elink{image of a Philosophical GNU} +{\url{http://www.gnu.org/graphics/philosophicalgnu.html}} [ +\elink{English}{\url{http://www.gnu.org/copyleft/lesser.html}} | +\elink{Japanese}{\url{http://www.gnu.org/copyleft/lesser.ja.html}} ] + +\begin{itemize} +\item + \elink{Why you shouldn't use the Lesser GPL for your next + library}{\url{http://www.gnu.org/philosophy/why-not-lgpl.html}} +\item + \elink{What to do if you see a possible LGPL + violation}{\url{http://www.gnu.org/copyleft/gpl-violation.html}} +\item + \elink{Translations of the LGPL} +{\url{http://www.gnu.org/copyleft/copyleft.html\#translationsLGPL}} +\item The GNU Lesser General Public License as a + \elink{text file}{\url{http://www.gnu.org/copyleft/lesser.txt}} +\item The GNU Lesser General Public License as a + \elink{Texinfo}{\url{http://www.gnu.org/copyleft/lesser.texi}} file + \end{itemize} + + +This GNU Lesser General Public License counts as the successor of the GNU +Library General Public License. For an explanation of why this change was +necessary, read the +\elink{Why you shouldn't use the Lesser GPL for your next +library}{\url{http://www.gnu.org/philosophy/why-not-lgpl.html}} article. + +\section{Table of Contents} +\index[general]{Table of Contents } +\index[general]{Contents!Table of } + +\begin{itemize} +\item + \label{TOC12} + \ilink{GNU LESSER GENERAL PUBLIC LICENSE}{SEC12} + +\begin{itemize} +\item + \label{TOC23} + \ilink{Preamble}{SEC23} +\item + \label{TOC34} + \ilink{TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND +MODIFICATION}{SEC34} +\item + \label{TOC45} + \ilink{How to Apply These Terms to Your New Libraries}{SEC45} +\end{itemize} + +\end{itemize} + + +\section{GNU LESSER GENERAL PUBLIC LICENSE} +\label{SEC12} +\index[general]{LICENSE!GNU LESSER GENERAL PUBLIC } +\index[general]{GNU LESSER GENERAL PUBLIC LICENSE } + +Version 2.1, February 1999 + +\footnotesize +\begin{verbatim} +Copyright (C) 1991, 1999 Free Software Foundation, Inc. +51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +[This is the first released version of the Lesser GPL. It also counts + as the successor of the GNU Library Public License, version 2, hence + the version number 2.1.] +\end{verbatim} +\normalsize + +\section{Preamble} +\label{SEC23} +\index[general]{Preamble } + +The licenses for most software are designed to take away your freedom to share +and change it. By contrast, the GNU General Public Licenses are intended to +guarantee your freedom to share and change free software\verb:--:to make sure the +software is free for all its users. + +This license, the Lesser General Public License, applies to some specially +designated software packages\verb:--:typically libraries\verb:--:of the Free Software +Foundation and other authors who decide to use it. You can use it too, but we +suggest you first think carefully about whether this license or the ordinary +General Public License is the better strategy to use in any particular case, +based on the explanations below. + +When we speak of free software, we are referring to freedom of use, not price. +Our General Public Licenses are designed to make sure that you have the +freedom to distribute copies of free software (and charge for this service if +you wish); that you receive source code or can get it if you want it; that you +can change the software and use pieces of it in new free programs; and that +you are informed that you can do these things. + +To protect your rights, we need to make restrictions that forbid distributors +to deny you these rights or to ask you to surrender these rights. These +restrictions translate to certain responsibilities for you if you distribute +copies of the library or if you modify it. + +For example, if you distribute copies of the library, whether gratis or for a +fee, you must give the recipients all the rights that we gave you. You must +make sure that they, too, receive or can get the source code. If you link +other code with the library, you must provide complete object files to the +recipients, so that they can relink them with the library after making changes +to the library and recompiling it. And you must show them these terms so they +know their rights. + +We protect your rights with a two-step method: (1) we copyright the library, +and (2) we offer you this license, which gives you legal permission to copy, +distribute and/or modify the library. + +To protect each distributor, we want to make it very clear that there is no +warranty for the free library. Also, if the library is modified by someone +else and passed on, the recipients should know that what they have is not the +original version, so that the original author's reputation will not be +affected by problems that might be introduced by others. + +Finally, software patents pose a constant threat to the existence of any free +program. We wish to make sure that a company cannot effectively restrict the +users of a free program by obtaining a restrictive license from a patent +holder. Therefore, we insist that any patent license obtained for a version of +the library must be consistent with the full freedom of use specified in this +license. + +Most GNU software, including some libraries, is covered by the ordinary GNU +General Public License. This license, the GNU Lesser General Public License, +applies to certain designated libraries, and is quite different from the +ordinary General Public License. We use this license for certain libraries in +order to permit linking those libraries into non-free programs. + +When a program is linked with a library, whether statically or using a shared +library, the combination of the two is legally speaking a combined work, a +derivative of the original library. The ordinary General Public License +therefore permits such linking only if the entire combination fits its +criteria of freedom. The Lesser General Public License permits more lax +criteria for linking other code with the library. + +We call this license the "Lesser" General Public License because it does +Less to protect the user's freedom than the ordinary General Public License. +It also provides other free software developers Less of an advantage over +competing non-free programs. These disadvantages are the reason we use the +ordinary General Public License for many libraries. However, the Lesser +license provides advantages in certain special circumstances. + +For example, on rare occasions, there may be a special need to encourage the +widest possible use of a certain library, so that it becomes a de-facto +standard. To achieve this, non-free programs must be allowed to use the +library. A more frequent case is that a free library does the same job as +widely used non-free libraries. In this case, there is little to gain by +limiting the free library to free software only, so we use the Lesser General +Public License. + +In other cases, permission to use a particular library in non-free programs +enables a greater number of people to use a large body of free software. For +example, permission to use the GNU C Library in non-free programs enables many +more people to use the whole GNU operating system, as well as its variant, the +GNU/Linux operating system. + +Although the Lesser General Public License is Less protective of the users' +freedom, it does ensure that the user of a program that is linked with the +Library has the freedom and the wherewithal to run that program using a +modified version of the Library. + +The precise terms and conditions for copying, distribution and modification +follow. Pay close attention to the difference between a "work based on the +library" and a "work that uses the library". The former contains code +derived from the library, whereas the latter must be combined with the library +in order to run. + +\section{TERMS AND CONDITIONS} +\label{SEC34} +\index[general]{CONDITIONS!TERMS AND } +\index[general]{TERMS AND CONDITIONS } + +TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + +{\bf 0.} This License Agreement applies to any software library or other +program which contains a notice placed by the copyright holder or other +authorized party saying it may be distributed under the terms of this Lesser +General Public License (also called "this License"). Each licensee is +addressed as "you". + +A "library" means a collection of software functions and/or data prepared so +as to be conveniently linked with application programs (which use some of +those functions and data) to form executables. + +The "Library", below, refers to any such software library or work which has +been distributed under these terms. A "work based on the Library" means +either the Library or any derivative work under copyright law: that is to say, +a work containing the Library or a portion of it, either verbatim or with +modifications and/or translated straightforwardly into another language. +(Hereinafter, translation is included without limitation in the term +"modification".) + +"Source code" for a work means the preferred form of the work for making +modifications to it. For a library, complete source code means all the source +code for all modules it contains, plus any associated interface definition +files, plus the scripts used to control compilation and installation of the +library. + +Activities other than copying, distribution and modification are not covered +by this License; they are outside its scope. The act of running a program +using the Library is not restricted, and output from such a program is covered +only if its contents constitute a work based on the Library (independent of +the use of the Library in a tool for writing it). Whether that is true depends +on what the Library does and what the program that uses the Library does. + +{\bf 1.} You may copy and distribute verbatim copies of the Library's complete +source code as you receive it, in any medium, provided that you conspicuously +and appropriately publish on each copy an appropriate copyright notice and +disclaimer of warranty; keep intact all the notices that refer to this License +and to the absence of any warranty; and distribute a copy of this License +along with the Library. + +You may charge a fee for the physical act of transferring a copy, and you may +at your option offer warranty protection in exchange for a fee. + +{\bf 2.} You may modify your copy or copies of the Library or any portion of +it, thus forming a work based on the Library, and copy and distribute such +modifications or work under the terms of Section 1 above, provided that you +also meet all of these conditions: + +\begin{itemize} +\item {\bf a)} The modified work must itself be a software library. +\item {\bf b)} You must cause the files modified to carry prominent notices + stating that you changed the files and the date of any change. +\item {\bf c)} You must cause the whole of the work to be licensed at no + charge to all third parties under the terms of this License. +\item {\bf d)} If a facility in the modified Library refers to a function or + a table of data to be supplied by an application program that uses the + facility, other than as an argument passed when the facility is invoked, then +you must make a good faith effort to ensure that, in the event an application +does not supply such function or table, the facility still operates, and +performs whatever part of its purpose remains meaningful. + +(For example, a function in a library to compute square roots has a purpose +that is entirely well-defined independent of the application. Therefore, +Subsection 2d requires that any application-supplied function or table used +by this function must be optional: if the application does not supply it, the +square root function must still compute square roots.) + +These requirements apply to the modified work as a whole. If identifiable +sections of that work are not derived from the Library, and can be reasonably +considered independent and separate works in themselves, then this License, +and its terms, do not apply to those sections when you distribute them as +separate works. But when you distribute the same sections as part of a whole +which is a work based on the Library, the distribution of the whole must be +on the terms of this License, whose permissions for other licensees extend to +the entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest your +rights to work written entirely by you; rather, the intent is to exercise the +right to control the distribution of derivative or collective works based on +the Library. + +In addition, mere aggregation of another work not based on the Library with +the Library (or with a work based on the Library) on a volume of a storage or +distribution medium does not bring the other work under the scope of this +License. +\end{itemize} + +{\bf 3.} You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do this, +you must alter all the notices that refer to this License, so that they refer +to the ordinary GNU General Public License, version 2, instead of to this +License. (If a newer version than version 2 of the ordinary GNU General Public +License has appeared, then you can specify that version instead if you wish.) +Do not make any other change in these notices. + +Once this change is made in a given copy, it is irreversible for that copy, so +the ordinary GNU General Public License applies to all subsequent copies and +derivative works made from that copy. + +This option is useful when you wish to copy part of the code of the Library +into a program that is not a library. + +{\bf 4.} You may copy and distribute the Library (or a portion or derivative +of it, under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you accompany it with the complete +corresponding machine-readable source code, which must be distributed under +the terms of Sections 1 and 2 above on a medium customarily used for software +interchange. + +If distribution of object code is made by offering access to copy from a +designated place, then offering equivalent access to copy the source code from +the same place satisfies the requirement to distribute the source code, even +though third parties are not compelled to copy the source along with the +object code. + +{\bf 5.} A program that contains no derivative of any portion of the Library, +but is designed to work with the Library by being compiled or linked with it, +is called a "work that uses the Library". Such a work, in isolation, is not +a derivative work of the Library, and therefore falls outside the scope of +this License. + +However, linking a "work that uses the Library" with the Library creates an +executable that is a derivative of the Library (because it contains portions +of the Library), rather than a "work that uses the library". The executable +is therefore covered by this License. Section 6 states terms for distribution +of such executables. + +When a "work that uses the Library" uses material from a header file that is +part of the Library, the object code for the work may be a derivative work of +the Library even though the source code is not. Whether this is true is +especially significant if the work can be linked without the Library, or if +the work is itself a library. The threshold for this to be true is not +precisely defined by law. + +If such an object file uses only numerical parameters, data structure layouts +and accessors, and small macros and small inline functions (ten lines or less +in length), then the use of the object file is unrestricted, regardless of +whether it is legally a derivative work. (Executables containing this object +code plus portions of the Library will still fall under Section 6.) + +Otherwise, if the work is a derivative of the Library, you may distribute the +object code for the work under the terms of Section 6. Any executables +containing that work also fall under Section 6, whether or not they are linked +directly with the Library itself. + +{\bf 6.} As an exception to the Sections above, you may also combine or link a +"work that uses the Library" with the Library to produce a work containing +portions of the Library, and distribute that work under terms of your choice, +provided that the terms permit modification of the work for the customer's own +use and reverse engineering for debugging such modifications. + +You must give prominent notice with each copy of the work that the Library is +used in it and that the Library and its use are covered by this License. You +must supply a copy of this License. If the work during execution displays +copyright notices, you must include the copyright notice for the Library among +them, as well as a reference directing the user to the copy of this License. +Also, you must do one of these things: + +\begin{itemize} +\item {\bf a)} Accompany the work with the complete corresponding + machine-readable source code for the Library including whatever changes were + used in the work (which must be distributed under Sections 1 and 2 above); +and, if the work is an executable linked with the Library, with the complete +machine-readable "work that uses the Library", as object code and/or source +code, so that the user can modify the Library and then relink to produce a +modified executable containing the modified Library. (It is understood that +the user who changes the contents of definitions files in the Library will +not necessarily be able to recompile the application to use the modified +definitions.) +\item {\bf b)} Use a suitable shared library mechanism for linking with the + Library. A suitable mechanism is one that (1) uses at run time a copy of the + library already present on the user's computer system, rather than copying +library functions into the executable, and (2) will operate properly with a +modified version of the library, if the user installs one, as long as the +modified version is interface-compatible with the version that the work was +made with. +\item {\bf c)} Accompany the work with a written offer, valid for at least + three years, to give the same user the materials specified in Subsection 6a, + above, for a charge no more than the cost of performing this distribution. +\item {\bf d)} If distribution of the work is made by offering access to copy + from a designated place, offer equivalent access to copy the above specified + materials from the same place. +\item {\bf e)} Verify that the user has already received a copy of these + materials or that you have already sent this user a copy. + \end{itemize} + +For an executable, the required form of the "work that uses the Library" +must include any data and utility programs needed for reproducing the +executable from it. However, as a special exception, the materials to be +distributed need not include anything that is normally distributed (in either +source or binary form) with the major components (compiler, kernel, and so on) +of the operating system on which the executable runs, unless that component +itself accompanies the executable. + +It may happen that this requirement contradicts the license restrictions of +other proprietary libraries that do not normally accompany the operating +system. Such a contradiction means you cannot use both them and the Library +together in an executable that you distribute. + +{\bf 7.} You may place library facilities that are a work based on the Library +side-by-side in a single library together with other library facilities not +covered by this License, and distribute such a combined library, provided that +the separate distribution of the work based on the Library and of the other +library facilities is otherwise permitted, and provided that you do these two +things: + +\begin{itemize} +\item {\bf a)} Accompany the combined library with a copy of the same work + based on the Library, uncombined with any other library facilities. This must + be distributed under the terms of the Sections above. +\item {\bf b)} Give prominent notice with the combined library of the fact + that part of it is a work based on the Library, and explaining where to find + the accompanying uncombined form of the same work. +\end{itemize} + +{\bf 8.} You may not copy, modify, sublicense, link with, or distribute the +Library except as expressly provided under this License. Any attempt otherwise +to copy, modify, sublicense, link with, or distribute the Library is void, and +will automatically terminate your rights under this License. However, parties +who have received copies, or rights, from you under this License will not have +their licenses terminated so long as such parties remain in full compliance. + +{\bf 9.} You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or distribute +the Library or its derivative works. These actions are prohibited by law if +you do not accept this License. Therefore, by modifying or distributing the +Library (or any work based on the Library), you indicate your acceptance of +this License to do so, and all its terms and conditions for copying, +distributing or modifying the Library or works based on it. + +{\bf 10.} Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the original +licensor to copy, distribute, link with or modify the Library subject to these +terms and conditions. You may not impose any further restrictions on the +recipients' exercise of the rights granted herein. You are not responsible for +enforcing compliance by third parties with this License. + +{\bf 11.} If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or otherwise) +that contradict the conditions of this License, they do not excuse you from +the conditions of this License. If you cannot distribute so as to satisfy +simultaneously your obligations under this License and any other pertinent +obligations, then as a consequence you may not distribute the Library at all. +For example, if a patent license would not permit royalty-free redistribution +of the Library by all those who receive copies directly or indirectly through +you, then the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, and +the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any patents or +other property right claims or to contest validity of any such claims; this +section has the sole purpose of protecting the integrity of the free software +distribution system which is implemented by public license practices. Many +people have made generous contributions to the wide range of software +distributed through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing to +distribute software through any other system and a licensee cannot impose that +choice. + +This section is intended to make thoroughly clear what is believed to be a +consequence of the rest of this License. + +{\bf 12.} If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the original +copyright holder who places the Library under this License may add an explicit +geographical distribution limitation excluding those countries, so that +distribution is permitted only in or among countries not thus excluded. In +such case, this License incorporates the limitation as if written in the body +of this License. + +{\bf 13.} The Free Software Foundation may publish revised and/or new versions +of the Lesser General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and "any later +version", you have the option of following the terms and conditions either of +that version or of any later version published by the Free Software +Foundation. If the Library does not specify a license version number, you may +choose any version ever published by the Free Software Foundation. + +{\bf 14.} If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, write to +the author to ask for permission. For software which is copyrighted by the +Free Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals of +preserving the free status of all derivatives of our free software and of +promoting the sharing and reuse of software generally. + +{\bf NO WARRANTY} + +{\bf 15.} BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE +THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR +IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO +THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY +PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION. + +{\bf 16.} IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO +LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR +THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. + +END OF TERMS AND CONDITIONS + +\section{How to Apply These Terms to Your New Libraries} +\label{SEC45} +\index[general]{Libraries!How to Apply These Terms to Your New } +\index[general]{How to Apply These Terms to Your New Libraries } + + +If you develop a new library, and you want it to be of the greatest possible +use to the public, we recommend making it free software that everyone can +redistribute and change. You can do so by permitting redistribution under +these terms (or, alternatively, under the terms of the ordinary General Public +License). + +To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + +\footnotesize +\begin{verbatim} +{\it one line to give the library's name and an idea of what it does.} +Copyright (C) {\it year} {\it name of author} +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version. +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 +USA +\end{verbatim} +\normalsize + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the library, if +necessary. Here is a sample; alter the names: + +\footnotesize +\begin{verbatim} +Yoyodyne, Inc., hereby disclaims all copyright interest in +the library "Frob" (a library for tweaking knobs) written +by James Random Hacker. +{\it signature of Ty Coon}, 1 April 1990 +Ty Coon, President of Vice +\end{verbatim} +\normalsize + +That's all there is to it! +Return to +\elink{GNU's home page}{\url{http://www.gnu.org/home.html}}. + +FSF \& GNU inquiries \& questions to +\elink{gnu@gnu.org}{mailto:gnu@gnu.org}. Other +\elink{ways to contact}{\url{http://www.gnu.org/home.html\#ContactInfo}} the FSF. + +Comments on these web pages to +\elink{webmasters@www.gnu.org}{mailto:webmasters@www.gnu.org}, send other +questions to +\elink{gnu@gnu.org}{mailto:gnu@gnu.org}. + +Copyright notice above. +Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, +Boston, MA 02110-1301 USA +USA + +Updated: 27 Nov 2000 paulv diff --git a/docs/manuals/fr/concepts/license.tex b/docs/manuals/fr/concepts/license.tex new file mode 100644 index 00000000..b50269f2 --- /dev/null +++ b/docs/manuals/fr/concepts/license.tex @@ -0,0 +1,115 @@ +%% +%% + +\chapter{Bacula Copyright, Trademark, and Licenses} +\label{LicenseChapter} +\index[general]{Licenses!Bacula Copyright Trademark} +\index[general]{Bacula Copyright, Trademark, and Licenses} + +There are a number of different licenses that are used in Bacula. +If you have a printed copy of this manual, the details of each of +the licenses referred to in this chapter can be found in the +online version of the manual at +\elink{http://www.bacula.org}{\url{http://www.bacula.org}}. + +\section{FDL} +\index[general]{FDL } + +The GNU Free Documentation License (FDL) is used for this manual, +which is a free and open license. This means that you may freely +reproduce it and even make changes to it. However, rather than +distribute your own version of this manual, we would much prefer +if you would send any corrections or changes to the Bacula project. + +The most recent version of the manual can always be found online +at \elink{http://www.bacula.org}{\url{http://www.bacula.org}}. + +% TODO: Point to appendix that has it + + +\section{GPL} +\index[general]{GPL } + +The vast bulk of the source code is released under the +\ilink{GNU General Public License version 2.}{GplChapter}. + +Most of this code is copyrighted: Copyright \copyright 2000-2007 +Free Software Foundation Europe e.V. + +Portions may be copyrighted by other people (ATT, the Free Software +Foundation, ...). These files are released under the GPL license. + +\section{LGPL} +\index[general]{LGPL } + +Some of the Bacula library source code is released under the +\ilink{GNU Lesser General Public License.}{LesserChapter} This +permits third parties to use these parts of our code in their proprietary +programs to interface to Bacula. + +\section{Public Domain} +\index[general]{Domain!Public } +\index[general]{Public Domain } + +Some of the Bacula code, or code that Bacula references, has been released +to the public domain. E.g. md5.c, SQLite. + +\section{Trademark} +\index[general]{Trademark } + +Bacula\raisebox{.6ex}{\textsuperscript{\textregistered}} is a registered +trademark of John Walker. + +We have trademarked the Bacula name to ensure that any program using the +name Bacula will be exactly compatible with the program that we have +released. The use of the name Bacula is restricted to software systems +that agree exactly with the program presented here. + +\section{Fiduciary License Agreement} +\index[general]{Fiduciary License Agreement } +Developers who have contributed significant changes to the Bacula code +should have signed a Fiduciary License Agreement (FLA), which +guarantees them the right to use the code they have developed, and also +ensures that the Free Software Foundation Europe (and thus the Bacula +project) has the rights to the code. This Fiduciary License Agreement +is found on the Bacula web site at: + +\elink{http://www.bacula.org/FLA-bacula.en.pdf}{\url{http://www.bacula.org/FLA-bacula.en.pdf}} + +and should be filled out then sent to: + +\begin{quote} + Free Software Foundation Europe \\ + Freedom Task Force \\ + Sumatrastrasse 25 \\ + 8006 Z\"{u}rich \\ + Switzerland \\ +\end{quote} + +Please note that the above address is different from the officially +registered office mentioned in the document. When you send in such a +complete document, please notify me: kern at sibbald dot com. + + +\section{Disclaimer} +\index[general]{Disclaimer } + +NO WARRANTY + +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE +PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE +STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE +PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, +INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND +FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND +PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, +YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY +COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE +PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE +OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR +DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR +A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH +HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. diff --git a/docs/manuals/fr/concepts/migration.tex b/docs/manuals/fr/concepts/migration.tex new file mode 100644 index 00000000..b0d49df2 --- /dev/null +++ b/docs/manuals/fr/concepts/migration.tex @@ -0,0 +1,445 @@ + +\chapter{Migration} +\label{MigrationChapter} +\index[general]{Migration} + +The term Migration, as used in the context of Bacula, means moving data from +one Volume to another. In particular it refers to a Job (similar to a backup +job) that reads data that was previously backed up to a Volume and writes +it to another Volume. As part of this process, the File catalog records +associated with the first backup job are purged. In other words, Migration +moves Bacula Job data from one Volume to another by reading the Job data +from the Volume it is stored on, writing it to a different Volume in a +different Pool, and then purging the database records for the first Job. + +The section process for which Job or Jobs are migrated +can be based on quite a number of different criteria such as: +\begin{itemize} +\item a single previous Job +\item a Volume +\item a Client +\item a regular expression matching a Job, Volume, or Client name +\item the time a Job has been on a Volume +\item high and low water marks (usage or occupation) of a Pool +\item Volume size +\end{itemize} + +The details of these selection criteria will be defined below. + +To run a Migration job, you must first define a Job resource very similar +to a Backup Job but with {\bf Type = Migrate} instead of {\bf Type = +Backup}. One of the key points to remember is that the Pool that is +specified for the migration job is the only pool from which jobs will +be migrated, with one exception noted below. In addition, the Pool to +which the selected Job or Jobs will be migrated is defined by the {\bf +Next Pool = ...} in the Pool resource specified for the Migration Job. + +Bacula permits pools to contain Volumes with different Media Types. +However, when doing migration, this is a very undesirable condition. For +migration to work properly, you should use pools containing only Volumes of +the same Media Type for all migration jobs. + +The migration job normally is either manually started or starts +from a Schedule much like a backup job. It searches +for a previous backup Job or Jobs that match the parameters you have +specified in the migration Job resource, primarily a {\bf Selection Type} +(detailed a bit later). Then for +each previous backup JobId found, the Migration Job will run a new Job which +copies the old Job data from the previous Volume to a new Volume in +the Migration Pool. It is possible that no prior Jobs are found for +migration, in which case, the Migration job will simply terminate having +done nothing, but normally at a minimum, three jobs are involved during a +migration: + +\begin{itemize} +\item The currently running Migration control Job. This is only + a control job for starting the migration child jobs. +\item The previous Backup Job (already run). The File records + for this Job are purged if the Migration job successfully + terminates. The original data remains on the Volume until + it is recycled and rewritten. +\item A new Migration Backup Job that moves the data from the + previous Backup job to the new Volume. If you subsequently + do a restore, the data will be read from this Job. +\end{itemize} + +If the Migration control job finds a number of JobIds to migrate (e.g. +it is asked to migrate one or more Volumes), it will start one new +migration backup job for each JobId found on the specified Volumes. +Please note that Migration doesn't scale too well since Migrations are +done on a Job by Job basis. This if you select a very large volume or +a number of volumes for migration, you may have a large number of +Jobs that start. Because each job must read the same Volume, they will +run consecutively (not simultaneously). + +\section{Migration Job Resource Directives} + +The following directives can appear in a Director's Job resource, and they +are used to define a Migration job. + +\begin{description} +\item [Pool = \lt{}Pool-name\gt{}] The Pool specified in the Migration + control Job is not a new directive for the Job resource, but it is + particularly important because it determines what Pool will be examined for + finding JobIds to migrate. The exception to this is when {\bf Selection + Type = SQLQuery}, in which case no Pool is used, unless you + specifically include it in the SQL query. Note, the Pool resource + referenced must contain a {\bf Next Pool = ...} directive to define + the Pool to which the data will be migrated. + +\item [Type = Migrate] + {\bf Migrate} is a new type that defines the job that is run as being a + Migration Job. A Migration Job is a sort of control job and does not have + any Files associated with it, and in that sense they are more or less like + an Admin job. Migration jobs simply check to see if there is anything to + Migrate then possibly start and control new Backup jobs to migrate the data + from the specified Pool to another Pool. + +\item [Selection Type = \lt{}Selection-type-keyword\gt{}] + The \lt{}Selection-type-keyword\gt{} determines how the migration job + will go about selecting what JobIds to migrate. In most cases, it is + used in conjunction with a {\bf Selection Pattern} to give you fine + control over exactly what JobIds are selected. The possible values + for \lt{}Selection-type-keyword\gt{} are: + \begin{description} + \item [SmallestVolume] This selection keyword selects the volume with the + fewest bytes from the Pool to be migrated. The Pool to be migrated + is the Pool defined in the Migration Job resource. The migration + control job will then start and run one migration backup job for + each of the Jobs found on this Volume. The Selection Pattern, if + specified, is not used. + + \item [OldestVolume] This selection keyword selects the volume with the + oldest last write time in the Pool to be migrated. The Pool to be + migrated is the Pool defined in the Migration Job resource. The + migration control job will then start and run one migration backup + job for each of the Jobs found on this Volume. The Selection + Pattern, if specified, is not used. + + \item [Client] The Client selection type, first selects all the Clients + that have been backed up in the Pool specified by the Migration + Job resource, then it applies the {\bf Selection Pattern} (defined + below) as a regular expression to the list of Client names, giving + a filtered Client name list. All jobs that were backed up for those + filtered (regexed) Clients will be migrated. + The migration control job will then start and run one migration + backup job for each of the JobIds found for those filtered Clients. + + \item [Volume] The Volume selection type, first selects all the Volumes + that have been backed up in the Pool specified by the Migration + Job resource, then it applies the {\bf Selection Pattern} (defined + below) as a regular expression to the list of Volume names, giving + a filtered Volume list. All JobIds that were backed up for those + filtered (regexed) Volumes will be migrated. + The migration control job will then start and run one migration + backup job for each of the JobIds found on those filtered Volumes. + + \item [Job] The Job selection type, first selects all the Jobs (as + defined on the {\bf Name} directive in a Job resource) + that have been backed up in the Pool specified by the Migration + Job resource, then it applies the {\bf Selection Pattern} (defined + below) as a regular expression to the list of Job names, giving + a filtered Job name list. All JobIds that were run for those + filtered (regexed) Job names will be migrated. Note, for a given + Job named, they can be many jobs (JobIds) that ran. + The migration control job will then start and run one migration + backup job for each of the Jobs found. + + \item [SQLQuery] The SQLQuery selection type, used the {\bf Selection + Pattern} as an SQL query to obtain the JobIds to be migrated. + The Selection Pattern must be a valid SELECT SQL statement for your + SQL engine, and it must return the JobId as the first field + of the SELECT. + + \item [PoolOccupancy] This selection type will cause the Migration job + to compute the total size of the specified pool for all Media Types + combined. If it exceeds the {\bf Migration High Bytes} defined in + the Pool, the Migration job will migrate all JobIds beginning with + the oldest Volume in the pool (determined by Last Write time) until + the Pool bytes drop below the {\bf Migration Low Bytes} defined in the + Pool. This calculation should be consider rather approximative because + it is made once by the Migration job before migration is begun, and + thus does not take into account additional data written into the Pool + during the migration. In addition, the calculation of the total Pool + byte size is based on the Volume bytes saved in the Volume (Media) +database + entries. The bytes calculate for Migration is based on the value stored + in the Job records of the Jobs to be migrated. These do not include the + Storage daemon overhead as is in the total Pool size. As a consequence, + normally, the migration will migrate more bytes than strictly necessary. + + \item [PoolTime] The PoolTime selection type will cause the Migration job to + look at the time each JobId has been in the Pool since the job ended. + All Jobs in the Pool longer than the time specified on {\bf Migration Time} + directive in the Pool resource will be migrated. + \end{description} + +\item [Selection Pattern = \lt{}Quoted-string\gt{}] + The Selection Patterns permitted for each Selection-type-keyword are + described above. + + For the OldestVolume and SmallestVolume, this + Selection pattern is not used (ignored). + + For the Client, Volume, and Job + keywords, this pattern must be a valid regular expression that will filter + the appropriate item names found in the Pool. + + For the SQLQuery keyword, this pattern must be a valid SELECT SQL statement + that returns JobIds. + +\end{description} + +\section{Migration Pool Resource Directives} + +The following directives can appear in a Director's Pool resource, and they +are used to define a Migration job. + +\begin{description} +\item [Migration Time = \lt{}time-specification\gt{}] + If a PoolTime migration is done, the time specified here in seconds (time + modifiers are permitted -- e.g. hours, ...) will be used. If the + previous Backup Job or Jobs selected have been in the Pool longer than + the specified PoolTime, then they will be migrated. + +\item [Migration High Bytes = \lt{}byte-specification\gt{}] + This directive specifies the number of bytes in the Pool which will + trigger a migration if a {\bf PoolOccupancy} migration selection + type has been specified. The fact that the Pool + usage goes above this level does not automatically trigger a migration + job. However, if a migration job runs and has the PoolOccupancy selection + type set, the Migration High Bytes will be applied. Bacula does not + currently restrict a pool to have only a single Media Type, so you + must keep in mind that if you mix Media Types in a Pool, the results + may not be what you want, as the Pool count of all bytes will be + for all Media Types combined. + +\item [Migration Low Bytes = \lt{}byte-specification\gt{}] + This directive specifies the number of bytes in the Pool which will + stop a migration if a {\bf PoolOccupancy} migration selection + type has been specified and triggered by more than Migration High + Bytes being in the pool. In other words, once a migration job + is started with {\bf PoolOccupancy} migration selection and it + determines that there are more than Migration High Bytes, the + migration job will continue to run jobs until the number of + bytes in the Pool drop to or below Migration Low Bytes. + +\item [Next Pool = \lt{}pool-specification\gt{}] + The Next Pool directive specifies the pool to which Jobs will be + migrated. This directive is required to define the Pool into which + the data will be migrated. Without this directive, the migration job + will terminate in error. + +\item [Storage = \lt{}storage-specification\gt{}] + The Storage directive specifies what Storage resource will be used + for all Jobs that use this Pool. It takes precedence over any other + Storage specifications that may have been given such as in the + Schedule Run directive, or in the Job resource. We highly recommend + that you define the Storage resource to be used in the Pool rather + than elsewhere (job, schedule run, ...). +\end{description} + +\section{Important Migration Considerations} +\index[general]{Important Migration Considerations} +\begin{itemize} +\item Each Pool into which you migrate Jobs or Volumes {\bf must} + contain Volumes of only one Media Type. + +\item Migration takes place on a JobId by JobId basis. That is + each JobId is migrated in its entirety and independently + of other JobIds. Once the Job is migrated, it will be + on the new medium in the new Pool, but for the most part, + aside from having a new JobId, it will appear with all the + same characteristics of the original job (start, end time, ...). + The column RealEndTime in the catalog Job table will contain the + time and date that the Migration terminated, and by comparing + it with the EndTime column you can tell whether or not the + job was migrated. The original job is purged of its File + records, and its Type field is changed from "B" to "M" to + indicate that the job was migrated. + +\item Jobs on Volumes will be Migration only if the Volume is + marked, Full, Used, or Error. Volumes that are still + marked Append will not be considered for migration. This + prevents Bacula from attempting to read the Volume at + the same time it is writing it. It also reduces other deadlock + situations, as well as avoids the problem that you migrate a + Volume and later find new files appended to that Volume. + +\item As noted above, for the Migration High Bytes, the calculation + of the bytes to migrate is somewhat approximate. + +\item If you keep Volumes of different Media Types in the same Pool, + it is not clear how well migration will work. We recommend only + one Media Type per pool. + +\item It is possible to get into a resource deadlock where Bacula does + not find enough drives to simultaneously read and write all the + Volumes needed to do Migrations. For the moment, you must take + care as all the resource deadlock algorithms are not yet implemented. + +\item Migration is done only when you run a Migration job. If you set a + Migration High Bytes and that number of bytes is exceeded in the Pool + no migration job will automatically start. You must schedule the + migration jobs, and they must run for any migration to take place. + +\item If you migrate a number of Volumes, a very large number of Migration + jobs may start. + +\item Figuring out what jobs will actually be migrated can be a bit complicated + due to the flexibility provided by the regex patterns and the number of + different options. Turning on a debug level of 100 or more will provide + a limited amount of debug information about the migration selection + process. + +\item Bacula currently does only minimal Storage conflict resolution, so you + must take care to ensure that you don't try to read and write to the + same device or Bacula may block waiting to reserve a drive that it + will never find. In general, ensure that all your migration + pools contain only one Media Type, and that you always + migrate to pools with different Media Types. + +\item The {\bf Next Pool = ...} directive must be defined in the Pool + referenced in the Migration Job to define the Pool into which the + data will be migrated. + +\item Pay particular attention to the fact that data is migrated on a Job + by Job basis, and for any particular Volume, only one Job can read + that Volume at a time (no simultaneous read), so migration jobs that + all reference the same Volume will run sequentially. This can be a + potential bottle neck and does not scale very well to large numbers + of jobs. + +\item Only migration of Selection Types of Job and Volume have + been carefully tested. All the other migration methods (time, + occupancy, smallest, oldest, ...) need additional testing. + +\item Migration is only implemented for a single Storage daemon. You + cannot read on one Storage daemon and write on another. +\end{itemize} + + +\section{Example Migration Jobs} +\index[general]{Example Migration Jobs} + +When you specify a Migration Job, you must specify all the standard +directives as for a Job. However, certain such as the Level, Client, and +FileSet, though they must be defined, are ignored by the Migration job +because the values from the original job used instead. + +As an example, suppose you have the following Job that +you run every night. To note: there is no Storage directive in the +Job resource; there is a Storage directive in each of the Pool +resources; the Pool to be migrated (File) contains a Next Pool +directive that defines the output Pool (where the data is written +by the migration job). + +\footnotesize +\begin{verbatim} +# Define the backup Job +Job { + Name = "NightlySave" + Type = Backup + Level = Incremental # default + Client=rufus-fd + FileSet="Full Set" + Schedule = "WeeklyCycle" + Messages = Standard + Pool = Default +} + +# Default pool definition +Pool { + Name = Default + Pool Type = Backup + AutoPrune = yes + Recycle = yes + Next Pool = Tape + Storage = File + LabelFormat = "File" +} + +# Tape pool definition +Pool { + Name = Tape + Pool Type = Backup + AutoPrune = yes + Recycle = yes + Storage = DLTDrive +} + +# Definition of File storage device +Storage { + Name = File + Address = rufus + Password = "ccV3lVTsQRsdIUGyab0N4sMDavui2hOBkmpBU0aQKOr9" + Device = "File" # same as Device in Storage daemon + Media Type = File # same as MediaType in Storage daemon +} + +# Definition of DLT tape storage device +Storage { + Name = DLTDrive + Address = rufus + Password = "ccV3lVTsQRsdIUGyab0N4sMDavui2hOBkmpBU0aQKOr9" + Device = "HP DLT 80" # same as Device in Storage daemon + Media Type = DLT8000 # same as MediaType in Storage daemon +} + +\end{verbatim} +\normalsize + +Where we have included only the essential information -- i.e. the +Director, FileSet, Catalog, Client, Schedule, and Messages resources are +omitted. + +As you can see, by running the NightlySave Job, the data will be backed up +to File storage using the Default pool to specify the Storage as File. + +Now, if we add the following Job resource to this conf file. + +\footnotesize +\begin{verbatim} +Job { + Name = "migrate-volume" + Type = Migrate + Level = Full + Client = rufus-fd + FileSet = "Full Set" + Messages = Standard + Pool = Default + Maximum Concurrent Jobs = 4 + Selection Type = Volume + Selection Pattern = "File" +} +\end{verbatim} +\normalsize + +and then run the job named {\bf migrate-volume}, all volumes in the Pool +named Default (as specified in the migrate-volume Job that match the +regular expression pattern {\bf File} will be migrated to tape storage +DLTDrive because the {\bf Next Pool} in the Default Pool specifies that +Migrations should go to the pool named {\bf Tape}, which uses +Storage {\bf DLTDrive}. + +If instead, we use a Job resource as follows: + +\footnotesize +\begin{verbatim} +Job { + Name = "migrate" + Type = Migrate + Level = Full + Client = rufus-fd + FileSet="Full Set" + Messages = Standard + Pool = Default + Maximum Concurrent Jobs = 4 + Selection Type = Job + Selection Pattern = ".*Save" +} +\end{verbatim} +\normalsize + +All jobs ending with the name Save will be migrated from the File Default to +the Tape Pool, or from File storage to Tape storage. diff --git a/docs/manuals/fr/concepts/mtx-changer.txt b/docs/manuals/fr/concepts/mtx-changer.txt new file mode 100644 index 00000000..10ef6d1c --- /dev/null +++ b/docs/manuals/fr/concepts/mtx-changer.txt @@ -0,0 +1,215 @@ +#!/bin/sh +# +# Bacula interface to mtx autoloader +# +# Created OCT/31/03 by Alexander Kuehn, derived from Ludwig Jaffe's script +# +# Works with the HP C1537A L708 DDS3 +# +#set -x +# these are the labels of the tapes in each virtual slot, not the slots! +labels="PSE-0001 PSE-0002 PSE-0003 PSE-0004 PSE-0005 PSE-0006 PSE-0007 PSE-0008 PSE-0009 PSE-0010 PSE-0011 PSE-0012" + +# who to send a mail to? +recipient=root@localhost +logfile=/var/log/mtx.log + +# Delay in seconds how often to check whether a new tape has been inserted +TAPEDELAY=10 # the default is every 10 seconds +echo `date` ":" $@ >>$logfile + +# change this if mt is not in the path (use different quotes!) +mt=`which mt` +grep=`which grep` +# +# how to run the console application? +console="/usr/local/sbin/console -c /usr/local/etc/console.conf" + +command="$1" + +#TAPEDRIVE0 holds the device/name of your 1st and only drive (Bacula supports only 1 drive currently) +#Read TAPEDRIVE from command line parameters +if [ -z "$2" ] ; then + TAPEDRIVE0=/dev/nsa0 +else + TAPEDRIVE0=$2 +fi + +#Read slot from command line parameters +if [ -z "$3" ] ; then + slot=`expr 1` +else + slot=`expr $3` +fi + +if [ -z "$command" ] ; then + echo "" + echo "The mtx-changer script for Bacula" + echo "---------------------------------" + echo "" + echo "usage: mtx-changer [slot]" + echo " mtx-changer" + echo "" + echo "Valid commands:" + echo "" + echo "unload Unloads a tape into the slot" + echo " from where it was loaded." + echo "load Loads a tape from the slot " + echo "list Lists full storage slots" + echo "loaded Gives slot from where the tape was loaded." + echo " 0 means the tape drive is empty." + echo "slots Gives Number of avialable slots." + echo "volumes List avialable slots and the label of the." + echo " tape in it (slot:volume)" + echo "Example:" + echo " mtx-changer load /dev/nst0 1 loads a tape from slot1" + echo " mtx-changer %a %o %S " + echo "" + exit 0 +fi + + +case "$command" in + unload) + # At first do mt -f /dev/st0 offline to unload the tape + # + # Check if you want to fool me + echo "unmount"|$console >/dev/null 2>/dev/null + echo "mtx-changer: Checking if drive is loaded before we unload. Request unload" >>$logfile + if $mt -f $TAPEDRIVE0 status >/dev/null 2>/dev/null ; then # mt says status ok + echo "mtx-changer: Doing mt -f $TAPEDRIVE0 rewoffl to rewind and unload the tape!" >>$logfile + $mt -f $TAPEDRIVE0 rewoffl + else + echo "mtx-changer: *** Don't fool me! *** The Drive $TAPEDRIVE0 is empty." >>$logfile + fi + exit 0 + ;; + + load) + #Let's check if drive is loaded before we load it + echo "mtx-changer: Checking if drive is loaded before we load. I Request loaded" >>$logfile + LOADEDVOL=`echo "status Storage"|$console|$grep $TAPEDRIVE0|grep ^Device|grep -v "not open."|grep -v "ERR="|grep -v "no Bacula volume is mounted"|sed -e s/^.*Volume\ //|cut -d\" -f2` +# if [ -z "$LOADEDVOL" ] ; then # this is wrong, becaus Bacula would try to use the tape if we mount it! +# LOADEDVOL=`echo "mount"|$console|$grep $TAPEDRIVE0|grep Device|grep -v "not open."|grep -v "ERR="|sed -e s/^.*Volume\ //|cut -d\" -f2` +# if [ -z "$LOADEDVOL" ] ; then +# echo "mtx-changer: The Drive $TAPEDRIVE0 is empty." >>$logfile +# else # restore state? +# if [ $LOADEDVOL = $3 ] ; then # requested Volume mounted -> exit +# echo "mtx-changer: *** Don't fool me! *** Tape $LOADEDVOL is already in drive $TAPEDRIVE0!" >>$logfile +# exit +# else # oops, wrong volume +# echo "unmount"|$console >/dev/null 2>/dev/null +# fi +# fi +# fi + if [ -z "$LOADEDVOL" ] ; then + echo "unmount"|$console >/dev/null 2>/dev/null + LOADEDVOL=0 + else + #Check if you want to fool me + if [ $LOADEDVOL = $3 ] ; then + echo "mtx-changer: *** Don't fool me! *** Tape $LOADEDVOL is already in drive $TAPEDRIVE0!" >>$logfile + exit + fi + echo "mtx-changer: The Drive $TAPEDRIVE0 is loaded with the tape $LOADEDVOL" >>$logfile + echo "mtx-changer: Unmounting..." >>$logfile + echo "unmount"|$console >/dev/null 2>/dev/null + fi + echo "mtx-changer: Unloading..." >>$logfile + echo "mtx-changer: Doing mt -f $TAPEDRIVE0 rewoffl to rewind and unload the tape!" >>$logfile + mt -f $TAPEDRIVE0 rewoffl 2>/dev/null + #Now we can load the drive as desired + echo "mtx-changer: Doing mtx -f $1 $2 $3" >>$logfile + # extract label for the mail + count=`expr 1` + for label in $labels ; do + if [ $slot -eq $count ] ; then volume=$label ; fi + count=`expr $count + 1` + done + + mail -s "Bacula needs volume $volume." $recipient </dev/null 2>/dev/null + while [ $? -ne 0 ] ; do + sleep $TAPEDELAY + $mt status >/dev/null 2>/dev/null + done + mail -s "Bacula says thank you." $recipient <>$logfile + echo "Loading finished." ; >>$logfile + echo "$slot" + exit 0 + ;; + + list) + echo "mtx-changer: Requested list" >>$logfile + LOADEDVOL=`echo "status Storage"|$console|$grep $TAPEDRIVE0|grep ^Device|grep -v "not open."|grep -v "ERR="|grep -v "no Bacula volume is mounted"|sed -e s/^.*Volume\ //|cut -d\" -f2` + if [ -z $LOADEDVOL ] ; then # try mounting + LOADEDVOL=`echo "mount"|$console|$grep $TAPEDRIVE0|grep Device|grep -v "not open."|grep -v "ERR="|sed -e s/^.*Volume\ //|cut -d\" -f2` + if [ -z $LOADEDVOL ] ; then # no luck + LOADEDVOL="_no_tape" + else # restore state + echo "unmount"|$console >/dev/null 2>/dev/null + fi + fi + count=`expr 1` + for label in $labels ; do + if [ "$label" != "$LOADEDVOL" ] ; then + printf "$count " + fi + count=`expr $count + 1` + done + printf "\n" + ;; + + loaded) + echo "mtx-changer: Request loaded, dev $TAPEDRIVE0" >>$logfile + LOADEDVOL=`echo "status Storage"|$console|$grep $TAPEDRIVE0|grep ^Device|grep -v "not open."|grep -v "ERR="|grep -v "no Bacula volume is mounted"|sed -e s/^.*Volume\ //|cut -d\" -f2` + if [ -z $LOADEDVOL ] ; then + LOADEDVOL=`echo "mount"|$console|$grep $TAPEDRIVE0|grep Device|grep -v "not open."|grep -v "ERR="|grep -v "no Bacula volume is mounted"|sed -e s/^.*Volume\ //|cut -d\" -f2` + if [ -z "$LOADEDVOL" ] ; then # no luck + echo "$TAPEDRIVE0 not mounted!" >>$logfile + else # restore state + echo "unmount"|$console >/dev/null 2>/dev/null + fi + fi + if [ -z "$LOADEDVOL" ] ; then + LOADEDVOL="_no_tape" >>$logfile + echo "0" + else + count=`expr 1` + for label in $labels ; do + if [ $LOADEDVOL = $label ] ; then echo $count ; fi + count=`expr $count + 1` + done + fi + exit 0 + ;; + + slots) + echo "mtx-changer: Request slots" >>$logfile + count=`expr 0` + for label in $labels ; do + count=`expr $count + 1` + done + echo $count + ;; + + volumes) + echo "mtx-changer: Request volumes" >>$logfile + count=`expr 1` + for label in $labels ; do + printf "$count:$label " + count=`expr $count + 1` + done + printf "\n" + ;; +esac diff --git a/docs/manuals/fr/concepts/pools.tex b/docs/manuals/fr/concepts/pools.tex new file mode 100644 index 00000000..10217f84 --- /dev/null +++ b/docs/manuals/fr/concepts/pools.tex @@ -0,0 +1,429 @@ +%% +%% + +\chapter{Automated Disk Backup} +\label{PoolsChapter} +\index[general]{Volumes!Using Pools to Manage} +\index[general]{Disk!Automated Backup} +\index[general]{Using Pools to Manage Volumes} +\index[general]{Automated Disk Backup} + +If you manage five or ten machines and have a nice tape backup, you don't need +Pools, and you may wonder what they are good for. In this chapter, you will +see that Pools can help you optimize disk storage space. The same techniques +can be applied to a shop that has multiple tape drives, or that wants to mount +various different Volumes to meet their needs. + +The rest of this chapter will give an example involving backup to disk +Volumes, but most of the information applies equally well to tape Volumes. + +\label{TheProblem} +\section{The Problem} +\index[general]{Problem} + +A site that I administer (a charitable organization) had a tape DDS-3 tape +drive that was failing. The exact reason for the failure is still unknown. +Worse yet, their full backup size is about 15GB whereas the capacity of their +broken DDS-3 was at best 8GB (rated 6/12). A new DDS-4 tape drive and the +necessary cassettes was more expensive than their budget could handle. + +\label{TheSolution} +\section{The Solution} +\index[general]{Solution} + +They want to maintain six months of backup data, and be able to access the old +files on a daily basis for a week, a weekly basis for a month, then monthly +for six months. In addition, offsite capability was not needed (well perhaps +it really is, but it was never used). Their daily changes amount to about +300MB on the average, or about 2GB per week. + +As a consequence, the total volume of data they need to keep to meet their +needs is about 100GB (15GB x 6 + 2GB x 5 + 0.3 x 7) = 102.1GB. + +The chosen solution was to buy a 120GB hard disk for next to nothing -- far +less than 1/10th the price of a tape drive and the cassettes to handle the +same amount of data, and to have Bacula write to disk files. + +The rest of this chapter will explain how to setup Bacula so that it would +automatically manage a set of disk files with the minimum sysadmin +intervention. The system has been running since 22 January 2004 until today +(23 June 2007) with no intervention, with the exception of adding +a second 120GB hard disk after a year because their needs grew +over that time to more than the 120GB (168GB to be exact). The only other +intervention I have made is a periodic (about once a year) Bacula upgrade. + +\label{OverallDesign} +\section{Overall Design} +\index[general]{Overall Design} +\index[general]{Design!Overall} + +Getting Bacula to write to disk rather than tape in the simplest case is +rather easy, and is documented in the previous chapter. In addition, all the +directives discussed here are explained in that chapter. We'll leave it to you +to look at the details there. If you haven't read it and are not familiar with +Pools, you probably should at least read it once quickly for the ideas before +continuing here. + +One needs to consider about what happens if we have only a single large Bacula +Volume defined on our hard disk. Everything works fine until the Volume fills, +then Bacula will ask you to mount a new Volume. This same problem applies to +the use of tape Volumes if your tape fills. Being a hard disk and the only one +you have, this will be a bit of a problem. It should be obvious that it is +better to use a number of smaller Volumes and arrange for Bacula to +automatically recycle them so that the disk storage space can be reused. The +other problem with a single Volume, is that until version 2.0.0, +Bacula did not seek within a disk Volume, so restoring a single file can take +more time than one would expect. + +As mentioned, the solution is to have multiple Volumes, or files on the disk. +To do so, we need to limit the use and thus the size of a single Volume, by +time, by number of jobs, or by size. Any of these would work, but we chose to +limit the use of a single Volume by putting a single job in each Volume with +the exception of Volumes containing Incremental backup where there will be 6 +jobs (a week's worth of data) per volume. The details of this will be +discussed shortly. This is a single client backup, so if you have multiple +clients you will need to multiply those numbers by the number of clients, +or use a different system for switching volumes, such as limiting the +volume size. + +The next problem to resolve is recycling of Volumes. As you noted from above, +the requirements are to be able to restore monthly for 6 months, weekly for a +month, and daily for a week. So to simplify things, why not do a Full save +once a month, a Differential save once a week, and Incremental saves daily. +Now since each of these different kinds of saves needs to remain valid for +differing periods, the simplest way to do this (and possibly the only) is to +have a separate Pool for each backup type. + +The decision was to use three Pools: one for Full saves, one for Differential +saves, and one for Incremental saves, and each would have a different number +of volumes and a different Retention period to accomplish the requirements. + +\label{FullPool} +\subsection{Full Pool} +\index[general]{Pool!Full} +\index[general]{Full Pool} + +Putting a single Full backup on each Volume, will require six Full save +Volumes, and a retention period of six months. The Pool needed to do that is: + +\footnotesize +\begin{verbatim} +Pool { + Name = Full-Pool + Pool Type = Backup + Recycle = yes + AutoPrune = yes + Volume Retention = 6 months + Maximum Volume Jobs = 1 + Label Format = Full- + Maximum Volumes = 9 +} +\end{verbatim} +\normalsize + +Since these are disk Volumes, no space is lost by having separate Volumes for +each backup (done once a month in this case). The items to note are the +retention period of six months (i.e. they are recycled after six months), that +there is one job per volume (Maximum Volume Jobs = 1), the volumes will be +labeled Full-0001, ... Full-0006 automatically. One could have labeled these +manually from the start, but why not use the features of Bacula. + +Six months after the first volume is used, it will be subject to pruning +and thus recycling, so with a maximum of 9 volumes, there should always be +3 volumes available (note, they may all be marked used, but they will be +marked purged and recycled as needed). + +If you have two clients, you would want to set {\bf Maximum Volume Jobs} to +2 instead of one, or set a limit on the size of the Volumes, and possibly +increase the maximum number of Volumes. + + +\label{DiffPool} +\subsection{Differential Pool} +\index[general]{Pool!Differential} +\index[general]{Differential Pool} + +For the Differential backup Pool, we choose a retention period of a bit longer +than a month and ensure that there is at least one Volume for each of the +maximum of five weeks in a month. So the following works: + +\footnotesize +\begin{verbatim} +Pool { + Name = Diff-Pool + Pool Type = Backup + Recycle = yes + AutoPrune = yes + Volume Retention = 40 days + Maximum Volume Jobs = 1 + Label Format = Diff- + Maximum Volumes = 10 +} +\end{verbatim} +\normalsize + +As you can see, the Differential Pool can grow to a maximum of 9 volumes, +and the Volumes are retained 40 days and thereafter they can be recycled. Finally +there is one job per volume. This, of course, could be tightened up a lot, but +the expense here is a few GB which is not too serious. + +If a new volume is used every week, after 40 days, one will have used 7 +volumes, and there should then always be 3 volumes that can be purged and +recycled. + +See the discussion above concering the Full pool for how to handle multiple +clients. + +\label{IncPool} +\subsection{Incremental Pool} +\index[general]{Incremental Pool} +\index[general]{Pool!Incremental} + +Finally, here is the resource for the Incremental Pool: + +\footnotesize +\begin{verbatim} +Pool { + Name = Inc-Pool + Pool Type = Backup + Recycle = yes + AutoPrune = yes + Volume Retention = 20 days + Maximum Volume Jobs = 6 + Label Format = Inc- + Maximum Volumes = 7 +} +\end{verbatim} +\normalsize + +We keep the data for 20 days rather than just a week as the needs require. To +reduce the proliferation of volume names, we keep a week's worth of data (6 +incremental backups) in each Volume. In practice, the retention period should +be set to just a bit more than a week and keep only two or three volumes +instead of five. Again, the lost is very little and as the system reaches the +full steady state, we can adjust these values so that the total disk usage +doesn't exceed the disk capacity. + +If you have two clients, the simplest thing to do is to increase the +maximum volume jobs from 6 to 12. As mentioned above, it is also possible +limit the size of the volumes. However, in that case, you will need to +have a better idea of the volume or add sufficient volumes to the pool so +that you will be assured that in the next cycle (after 20 days) there is +at least one volume that is pruned and can be recycled. + + +\label{Example} +\section{The Actual Conf Files} +\index[general]{Files!Actual Conf} +\index[general]{Actual Conf Files} + +The following example shows you the actual files used, with only a few minor +modifications to simplify things. + +The Director's configuration file is as follows: + +\footnotesize +\begin{verbatim} +Director { # define myself + Name = bacula-dir + DIRport = 9101 + QueryFile = "/home/bacula/bin/query.sql" + WorkingDirectory = "/home/bacula/working" + PidDirectory = "/home/bacula/working" + Maximum Concurrent Jobs = 1 + Password = " *** CHANGE ME ***" + Messages = Standard +} +# By default, this job will back up to disk in /tmp +Job { + Name = client + Type = Backup + Client = client-fd + FileSet = "Full Set" + Schedule = "WeeklyCycle" + Storage = File + Messages = Standard + Pool = Default + Full Backup Pool = Full-Pool + Incremental Backup Pool = Inc-Pool + Differential Backup Pool = Diff-Pool + Write Bootstrap = "/home/bacula/working/client.bsr" + Priority = 10 +} + +# Backup the catalog database (after the nightly save) +Job { + Name = "BackupCatalog" + Type = Backup + Client = client-fd + FileSet="Catalog" + Schedule = "WeeklyCycleAfterBackup" + Storage = File + Messages = Standard + Pool = Default + # This creates an ASCII copy of the catalog + # WARNING!!! Passing the password via the command line is insecure. + # see comments in make_catalog_backup for details. + RunBeforeJob = "/home/bacula/bin/make_catalog_backup bacula bacula" + # This deletes the copy of the catalog + RunAfterJob = "/home/bacula/bin/delete_catalog_backup" + Write Bootstrap = "/home/bacula/working/BackupCatalog.bsr" + Priority = 11 # run after main backup +} + +# Standard Restore template, to be changed by Console program +Job { + Name = "RestoreFiles" + Type = Restore + Client = havana-fd + FileSet="Full Set" + Storage = File + Messages = Standard + Pool = Default + Where = /tmp/bacula-restores +} + + + +# List of files to be backed up +FileSet { + Name = "Full Set" + Include = { Options { signature=SHA1; compression=GZIP9 } + File = / + File = /usr + File = /home + File = /boot + File = /var + File = /opt + } + Exclude = { + File = /proc + File = /tmp + File = /.journal + File = /.fsck + ... + } +} +Schedule { + Name = "WeeklyCycle" + Run = Level=Full 1st sun at 2:05 + Run = Level=Differential 2nd-5th sun at 2:05 + Run = Level=Incremental mon-sat at 2:05 +} + +# This schedule does the catalog. It starts after the WeeklyCycle +Schedule { + Name = "WeeklyCycleAfterBackup" + Run = Level=Full sun-sat at 2:10 +} + +# This is the backup of the catalog +FileSet { + Name = "Catalog" + Include { Options { signature=MD5 } + File = /home/bacula/working/bacula.sql + } +} + +Client { + Name = client-fd + Address = client + FDPort = 9102 + Catalog = MyCatalog + Password = " *** CHANGE ME ***" + AutoPrune = yes # Prune expired Jobs/Files + Job Retention = 6 months + File Retention = 60 days +} + +Storage { + Name = File + Address = localhost + SDPort = 9103 + Password = " *** CHANGE ME ***" + Device = FileStorage + Media Type = File +} + +Catalog { + Name = MyCatalog + dbname = bacula; user = bacula; password = "" +} + +Pool { + Name = Full-Pool + Pool Type = Backup + Recycle = yes # automatically recycle Volumes + AutoPrune = yes # Prune expired volumes + Volume Retention = 6 months + Maximum Volume Jobs = 1 + Label Format = Full- + Maximum Volumes = 9 +} + +Pool { + Name = Inc-Pool + Pool Type = Backup + Recycle = yes # automatically recycle Volumes + AutoPrune = yes # Prune expired volumes + Volume Retention = 20 days + Maximum Volume Jobs = 6 + Label Format = Inc- + Maximum Volumes = 7 +} + +Pool { + Name = Diff-Pool + Pool Type = Backup + Recycle = yes + AutoPrune = yes + Volume Retention = 40 days + Maximum Volume Jobs = 1 + Label Format = Diff- + Maximum Volumes = 10 +} + +Messages { + Name = Standard + mailcommand = "bsmtp -h mail.domain.com -f \"\(Bacula\) %r\" + -s \"Bacula: %t %e of %c %l\" %r" + operatorcommand = "bsmtp -h mail.domain.com -f \"\(Bacula\) %r\" + -s \"Bacula: Intervention needed for %j\" %r" + mail = root@domain.com = all, !skipped + operator = root@domain.com = mount + console = all, !skipped, !saved + append = "/home/bacula/bin/log" = all, !skipped +} +\end{verbatim} +\normalsize + +and the Storage daemon's configuration file is: + +\footnotesize +\begin{verbatim} +Storage { # definition of myself + Name = bacula-sd + SDPort = 9103 # Director's port + WorkingDirectory = "/home/bacula/working" + Pid Directory = "/home/bacula/working" +} +Director { + Name = bacula-dir + Password = " *** CHANGE ME ***" +} +Device { + Name = FileStorage + Media Type = File + Archive Device = /files/bacula + LabelMedia = yes; # lets Bacula label unlabeled media + Random Access = Yes; + AutomaticMount = yes; # when device opened, read it + RemovableMedia = no; + AlwaysOpen = no; +} +Messages { + Name = Standard + director = bacula-dir = all +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/concepts/projects.tex b/docs/manuals/fr/concepts/projects.tex new file mode 100644 index 00000000..f118e791 --- /dev/null +++ b/docs/manuals/fr/concepts/projects.tex @@ -0,0 +1,28 @@ +%% +%% + +\chapter{Bacula Projects} +\label{ProjectsChapter} +\index[general]{Projects!Bacula } +\index[general]{Bacula Projects } + +Once a new major version of Bacula is released, the Bacula +users will vote on a list of new features. This vote is used +as the main element determining what new features will be +implemented for the next version. Generally, the development time +for a new release is between four to nine months. Sometimes it may be +a bit longer, but in that case, there will be a number of bug fix +updates to the currently released version. + +For the current list of project, please see the projects page in the CVS +at: \elink{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/projects} +{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/projects} +see the {\bf projects} file in the main source directory. The projects +file is updated approximately once every six months. + +Separately from the project list, Kern maintains a current list of +tasks as well as ideas, feature requests, and occasionally design +notes. This list is updated roughly weekly (sometimes more often). +For a current list of tasks you can see {\bf kernstodo} in the Source Forge +CVS at \elink{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/kernstodo} +{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/kernstodo}. diff --git a/docs/manuals/fr/concepts/python.tex b/docs/manuals/fr/concepts/python.tex new file mode 100644 index 00000000..40e1b2e0 --- /dev/null +++ b/docs/manuals/fr/concepts/python.tex @@ -0,0 +1,479 @@ +%% +%% + +\chapter{Python Scripting} +\label{PythonChapter} +\index[general]{Python Scripting} +\index[general]{Scripting!Python} + +You may be asking what Python is and why a scripting language is +needed in Bacula. The answer to the first question is that Python +is an Object Oriented scripting language with features similar +to those found in Perl, but the syntax of the language is much +cleaner and simpler. The answer to why have scripting in Bacula is to +give the user more control over the whole backup process. Probably +the simplest example is when Bacula needs a new Volume name, with +a scripting language such as Python, you can generate any name +you want, based on the current state of Bacula. + +\section{Python Configuration} +\index[general]{Python Configuration} +\index[general]{Configuration!Python} + +Python must be enabled during the configuration process by adding +a \verb:--:with-python, and possibly specifying an alternate +directory if your Python is not installed in a standard system +location. If you are using RPMs you will need the python-devel package +installed. + +When Python is configured, it becomes an integral part of Bacula and +runs in Bacula's address space, so even though it is an interpreted +language, it is very efficient. + +When the Director starts, it looks to see if you have a {\bf +Scripts Directory} Directive defined (normal default {\bf +/etc/bacula/scripts}, if so, it looks in that directory for a file named +{\bf DirStartUp.py}. If it is found, Bacula will pass this file to Python +for execution. The {\bf Scripts Directory} is a new directive that you add +to the Director resource of your bacula-dir.conf file. + +Note: Bacula does not install Python scripts by default because these +scripts are for you to program. This means that with a default +installation with Python enabled, Bacula will print the following error +message: + +\begin{verbatim} +09-Jun 15:14 bacula-dir: ERROR in pythonlib.c:131 Could not import +Python script /etc/bacula/scripts/DirStartUp. Python disabled. +\end{verbatim} + +The source code directory {\bf examples/python} contains sample scripts +for DirStartUp.py, SDStartUp.py, and FDStartUp.py that you might want +to use as a starting point. Normally, your scripts directory (at least +where you store the Python scripts) should be writable by Bacula, because +Python will attempt to write a compiled version of the scripts (e.g. +DirStartUp.pyc) back to that directory. + +When starting with the sample scripts, you can delete any part that +you will not need, but you should keep all the Bacula Event and Job Event +definitions. If you do not want a particular event, simply replace the +existing code with a {\bf noop = 1}. + +\section{Bacula Events} +\index[general]{Bacula Events} +\index[general]{Events} +A Bacula event is a point in the Bacula code where Bacula +will call a subroutine (actually a method) that you have +defined in the Python StartUp script. Events correspond +to some significant event such as a Job Start, a Job End, +Bacula needs a new Volume Name, ... When your script is +called, it will have access to all the Bacula variables +specific to the Job (attributes of the Job Object), and +it can even call some of the Job methods (subroutines) +or set new values in the Job attributes, such as the +Priority. You will see below how the events are used. + +\section{Python Objects} +\index[general]{Python Objects} +\index[general]{Objects!Python} + +There are four Python objects that you will need to work with: +\begin{description} +\item [The Bacula Object] + The Bacula object is created by the Bacula daemon (the Director + in the present case) when the daemon starts. It is available to + the Python startup script, {\bf DirStartup.py}, by importing the + Bacula definitions with {\bf import bacula}. The methods + available with this object are described below. + +\item [The Bacula Events Class] + You create this class in the startup script, and you pass + it to the Bacula Object's {\bf set\_events} method. The + purpose of the Bacula Events Class is to define what global + or daemon events you want to monitor. When one of those events + occurs, your Bacula Events Class will be called at the method + corresponding to the event. There are currently three events, + JobStart, JobEnd, and Exit, which are described in detail below. + +\item [The Job Object] + When a Job starts, and assuming you have defined a JobStart method + in your Bacula Events Class, Bacula will create a Job Object. This + object will be passed to the JobStart event. The Job Object has a + has good number of read-only members or attributes providing many + details of the Job, and it also has a number of writable attributes + that allow you to pass information into the Job. These attributes + are described below. + +\item [The Job Events Class] + You create this class in the JobStart method of your Bacula Events + class, and it allows you to define which of the possible Job Object + events you want to see. You must pass an instance of your Job Events + class to the Job Object set\_events() method. + Normally, you will probably only have one + Job Events Class, which will be instantiated for each Job. However, + if you wish to see different events in different Jobs, you may have + as many Job Events classes as you wish. +\end{description} + + +The first thing the startup script must do is to define what global Bacula +events (daemon events), it wants to see. This is done by creating a +Bacula Events class, instantiating it, then passing it to the +{\bf set\_events} method. There are three possible +events. + +\begin{description} +\item [JobStart] + \index[dir]{JobStart} + This Python method, if defined, will be called each time a Job is started. + The method is passed the class instantiation object as the first argument, + and the Bacula Job object as the second argument. The Bacula Job object + has several built-in methods, and you can define which ones you + want called. If you do not define this method, you will not be able + to interact with Bacula jobs. + +\item [JobEnd] + This Python method, if defined, will be called each time a Job terminates. + The method is passed the class instantiation object as the first argument, + and the Bacula Job object as the second argument. + +\item [Exit] + This Python method, if defined, will be called when the Director terminates. + The method is passed the class instantiation object as the first argument. +\end{description} + +Access to the Bacula variables and methods is done with: + + import bacula + +The following are the read-only attributes provided by the bacula object. +\begin{description} +\item [Name] +\item [ConfigFile] +\item [WorkingDir] +\item [Version] string consisting of "Version Build-date" +\end{description} + + +A simple definition of the Bacula Events Class might be the following: + +\footnotesize +\begin{verbatim} +import sys, bacula +class BaculaEvents: + def JobStart(self, job): + ... +\end{verbatim} +\normalsize + +Then to instantiate the class and pass it to Bacula, you +would do: + +\footnotesize +\begin{verbatim} +bacula.set_events(BaculaEvents()) # register Bacula Events wanted +\end{verbatim} +\normalsize + +And at that point, each time a Job is started, your BaculaEvents JobStart +method will be called. + +Now to actually do anything with a Job, you must define which Job events +you want to see, and this is done by defining a JobEvents class containing +the methods you want called. Each method name corresponds to one of the +Job Events that Bacula will generate. + +A simple Job Events class might look like the following: + +\footnotesize +\begin{verbatim} +class JobEvents: + def NewVolume(self, job): + ... +\end{verbatim} +\normalsize + +Here, your JobEvents class method NewVolume will be called each time +the Job needs a new Volume name. To actually register the events defined +in your class with the Job, you must instantiate the JobEvents class and +set it in the Job {\bf set\_events} variable. Note, this is a bit different +from how you registered the Bacula events. The registration process must +be done in the Bacula JobStart event (your method). So, you would modify +Bacula Events (not the Job events) as follows: + +\footnotesize +\begin{verbatim} +import sys, bacula +class BaculaEvents: + def JobStart(self, job): + events = JobEvents() # create instance of Job class + job.set_events(events) # register Job events desired + ... +\end{verbatim} +\normalsize + +When a job event is triggered, the appropriate event definition is +called in the JobEvents class. This is the means by which your Python +script or code gets control. Once it has control, it may read job +attributes, or set them. See below for a list of read-only attributes, +and those that are writable. + +In addition, the Bacula {\bf job} object in the Director has +a number of methods (subroutines) that can be called. They +are: +\begin{description} +\item [set\_events] The set\_events method takes a single + argument, which is the instantiation of the Job Events class + that contains the methods that you want called. The method + names that will be called must correspond to the Bacula + defined events. You may define additional methods but Bacula + will not use them. +\item [run] The run method takes a single string + argument, which is the run command (same as in the Console) + that you want to submit to start a new Job. The value + returned by the run method is the JobId of the job that + started, or -1 if there was an error. +\item [write] The write method is used to be able to send + print output to the Job Report. This will be described later. +\item[cancel] The cancel method takes a single integer argument, + which is a JobId. If JobId is found, it will be canceled. +\item [DoesVolumeExist] The DoesVolumeExist method takes a single + string argument, which is the Volume name, and returns + 1 if the volume exists in the Catalog and 0 if the volume + does not exist. +\end{description} + +The following attributes are read/write within the Director +for the {\bf job} object. + +\begin{description} +\item [Priority] Read or set the Job priority. + Note, that setting a Job Priority is effective only before + the Job actually starts. +\item [Level] This attribute contains a string representing the Job + level, e.g. Full, Differential, Incremental, ... if read. + The level can also be set. +\end{description} + +The following read-only attributes are available within the Director +for the {\bf job} object. + +\begin{description} +\item [Type] This attribute contains a string representing the Job + type, e.g. Backup, Restore, Verify, ... +\item [JobId] This attribute contains an integer representing the + JobId. +\item [Client] This attribute contains a string with the name of the + Client for this job. +\item [NumVols] This attribute contains an integer with the number of + Volumes in the Pool being used by the Job. +\item [Pool] This attribute contains a string with the name of the Pool + being used by the Job. +\item [Storage] This attribute contains a string with the name of the + Storage resource being used by the Job. +\item [Catalog] This attribute contains a string with the name of the + Catalog resource being used by the Job. +\item [MediaType] This attribute contains a string with the name of the + Media Type associated with the Storage resource being used by the Job. +\item [Job] This attribute contains a string containing the name of the + Job resource used by this job (not unique). +\item [JobName] This attribute contains a string representing the full + unique Job name. +\item [JobStatus] This attribute contains a single character string + representing the current Job status. The status may change + during execution of the job. It may take on the following + values: + \begin{description} + \item [C] Created, not yet running + \item [R] Running + \item [B] Blocked + \item [T] Completed successfully + \item [E] Terminated with errors + \item [e] Non-fatal error + \item [f] Fatal error + \item [D] Verify found differences + \item [A] Canceled by user + \item [F] Waiting for Client + \item [S] Waiting for Storage daemon + \item [m] Waiting for new media + \item [M] Waiting for media mount + \item [s] Waiting for storage resource + \item [j] Waiting for job resource + \item [c] Waiting for client resource + \item [d] Waiting on maximum jobs + \item [t] Waiting on start time + \item [p] Waiting on higher priority jobs + \end{description} + +\item [Priority] This attribute contains an integer with the priority + assigned to the job. +\item [CatalogRes] tuple consisting of (DBName, Address, User, + Password, Socket, Port, Database Vendor) taken from the Catalog resource + for the Job with the exception of Database Vendor, which is + one of the following: MySQL, PostgreSQL, SQLite, Internal, + depending on what database you configured. +\item [VolumeName] + After a Volume has been purged, this attribute will contain the + name of that Volume. At other times, this value may have no meaning. +\end{description} + +The following write-only attributes are available within the +Director: + +\begin{description} +\item [JobReport] Send line to the Job Report. +\item [VolumeName] Set a new Volume name. Valid only during the + NewVolume event. +\end{description} + +\section{Python Console Command} +\index[general]{Python Console Command} +\index[general]{Console Command!Python} + +There is a new Console command named {\bf python}. It takes +a single argument {\bf restart}. Example: +\begin{verbatim} + python restart +\end{verbatim} + +This command restarts the Python interpreter in the Director. +This can be useful when you are modifying the DirStartUp script, +because normally Python will cache it, and thus the +script will be read one time. + +\section{Debugging Python Scripts} +\index[general]{Debugging Python Scripts} +In general, you debug your Python scripts by using print statements. +You can also develop your script or important parts of it as a +separate file using the Python interpreter to run it. Once you +have it working correctly, you can then call the script from +within the Bacula Python script (DirStartUp.py). + +If you are having problems loading DirStartUp.py, you will probably +not get any error messages because Bacula can only print Python +error messages after the Python interpreter is started. However, you +may be able to see the error messages by starting Bacula in +a shell window with the {\bf -d1} option on the command line. That +should cause the Python error messages to be printed in the shell +window. + +If you are getting error messages such as the following when +loading DirStartUp.py: + +\begin{verbatim} + Traceback (most recent call last): + File "/etc/bacula/scripts/DirStartUp.py", line 6, in ? + import time, sys, bacula + ImportError: /usr/lib/python2.3/lib-dynload/timemodule.so: undefined + symbol: PyInt_FromLong + bacula-dir: pythonlib.c:134 Python Import error. +\end{verbatim} + +It is because the DirStartUp script is calling a dynamically loaded +module (timemodule.so in the above case) that then tries to use +Python functions exported from the Python interpreter (in this case +PyInt\_FromLong). The way Bacula is currently linked with Python does +not permit this. The solution to the problem is to put such functions +(in this case the import of time into a separate Python script, which +will do your calculations and return the values you want. Then call +(not import) this script from the Bacula DirStartUp.py script, and +it all should work as you expect. + + + + + +\section{Python Example} +\index[general]{Python Example} +\index[general]{Example!Python} + +An example script for the Director startup file is provided in +{\bf examples/python/DirStartup.py} as follows: + +\footnotesize +\begin{verbatim} +# +# Bacula Python interface script for the Director +# + +# You must import both sys and bacula +import sys, bacula + +# This is the list of Bacula daemon events that you +# can receive. +class BaculaEvents(object): + def __init__(self): + # Called here when a new Bacula Events class is + # is created. Normally not used + noop = 1 + + def JobStart(self, job): + """ + Called here when a new job is started. If you want + to do anything with the Job, you must register + events you want to receive. + """ + events = JobEvents() # create instance of Job class + events.job = job # save Bacula's job pointer + job.set_events(events) # register events desired + sys.stderr = events # send error output to Bacula + sys.stdout = events # send stdout to Bacula + jobid = job.JobId; client = job.Client + numvols = job.NumVols + job.JobReport="Python Dir JobStart: JobId=%d Client=%s NumVols=%d\n" % (jobid,client,numvols) + + # Bacula Job is going to terminate + def JobEnd(self, job): + jobid = job.JobId + client = job.Client + job.JobReport="Python Dir JobEnd output: JobId=%d Client=%s.\n" % (jobid, client) + + # Called here when the Bacula daemon is going to exit + def Exit(self, job): + print "Daemon exiting." + +bacula.set_events(BaculaEvents()) # register daemon events desired + +""" + These are the Job events that you can receive. +""" +class JobEvents(object): + def __init__(self): + # Called here when you instantiate the Job. Not + # normally used + noop = 1 + + def JobInit(self, job): + # Called when the job is first scheduled + noop = 1 + + def JobRun(self, job): + # Called just before running the job after initializing + # This is the point to change most Job parameters. + # It is equivalent to the JobRunBefore point. + noop = 1 + + def NewVolume(self, job): + # Called when Bacula wants a new Volume name. The Volume + # name returned, if any, must be stored in job.VolumeName + jobid = job.JobId + client = job.Client + numvol = job.NumVols; + print job.CatalogRes + job.JobReport = "JobId=%d Client=%s NumVols=%d" % (jobid, client, numvol) + job.JobReport="Python before New Volume set for Job.\n" + Vol = "TestA-%d" % numvol + job.JobReport = "Exists=%d TestA-%d" % (job.DoesVolumeExist(Vol), numvol) + job.VolumeName="TestA-%d" % numvol + job.JobReport="Python after New Volume set for Job.\n" + return 1 + + def VolumePurged(self, job): + # Called when a Volume is purged. The Volume name can be referenced + # with job.VolumeName + noop = 1 + + + +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/concepts/recycling.tex b/docs/manuals/fr/concepts/recycling.tex new file mode 100644 index 00000000..c2962d51 --- /dev/null +++ b/docs/manuals/fr/concepts/recycling.tex @@ -0,0 +1,717 @@ +%% +%% + +\chapter{Automatic Volume Recycling} +\label{RecyclingChapter} +\index[general]{Recycling!Automatic Volume } +\index[general]{Automatic Volume Recycling } + +By default, once Bacula starts writing a Volume, it can append to the +volume, but it will not overwrite the existing data thus destroying it. +However when Bacula {\bf recycles} a Volume, the Volume becomes available +for being reused, and Bacula can at some later time overwrite the previous +contents of that Volume. Thus all previous data will be lost. If the +Volume is a tape, the tape will be rewritten from the beginning. If the +Volume is a disk file, the file will be truncated before being rewritten. + +You may not want Bacula to automatically recycle (reuse) tapes. This would +require a large number of tapes though, and in such a case, it is possible +to manually recycle tapes. For more on manual recycling, see the section +entitled \ilink{ Manually Recycling Volumes}{manualrecycling} below in this +chapter. + +Most people prefer to have a Pool of tapes that are used for daily backups and +recycled once a week, another Pool of tapes that are used for Full backups +once a week and recycled monthly, and finally a Pool of tapes that are used +once a month and recycled after a year or two. With a scheme like this, the +number of tapes in your pool or pools remains constant. + +By properly defining your Volume Pools with appropriate Retention periods, +Bacula can manage the recycling (such as defined above) automatically. + +Automatic recycling of Volumes is controlled by four records in the {\bf +Pool} resource definition in the Director's configuration file. These four +records are: + +\begin{itemize} +\item AutoPrune = yes +\item VolumeRetention = \lt{}time\gt{} +\item Recycle = yes +\item RecyclePool = \lt{}APool\gt{} (\textit{This require bacula 2.1.4 or greater}) +\end{itemize} + +The above three directives are all you need assuming that you fill +each of your Volumes then wait the Volume Retention period before +reusing them. If you want Bacula to stop using a Volume and recycle +it before it is full, you will need to use one or more additional +directives such as: +\begin{itemize} +\item Use Volume Once = yes +\item Volume Use Duration = ttt +\item Maximum Volume Jobs = nnn +\item Maximum Volume Bytes = mmm +\end{itemize} +Please see below and +the \ilink{Basic Volume Management}{DiskChapter} chapter +of this manual for more complete examples. + +Automatic recycling of Volumes is performed by Bacula only when it wants a +new Volume and no appendable Volumes are available in the Pool. It will then +search the Pool for any Volumes with the {\bf Recycle} flag set and whose +Volume Status is {\bf Full}. At that point, the recycling occurs in two steps. +The first is that the Catalog for a Volume must be purged of all Jobs and +Files contained on that Volume, and the second step is the actual recycling of +the Volume. The Volume will be purged if the VolumeRetention period has +expired. When a Volume is marked as Purged, it means that no Catalog records +reference that Volume, and the Volume can be recycled. Until recycling +actually occurs, the Volume data remains intact. If no Volumes can be found +for recycling for any of the reasons stated above, Bacula will request +operator intervention (i.e. it will ask you to label a new volume). + +A key point mentioned above, that can be a source of frustration, is that Bacula +will only recycle purged Volumes if there is no other appendable Volume +available, otherwise, it will always write to an appendable Volume before +recycling even if there are Volume marked as Purged. This preserves your data +as long as possible. So, if you wish to "force" Bacula to use a purged +Volume, you must first ensure that no other Volume in the Pool is marked {\bf +Append}. If necessary, you can manually set a volume to {\bf Full}. The reason +for this is that Bacula wants to preserve the data on your old tapes (even +though purged from the catalog) as long as absolutely possible before +overwriting it. There are also a number of directives such as +{\bf Volume Use Duration} that will automatically mark a volume as {\bf +Used} and thus no longer appendable. + +\label{AutoPruning} +\section{Automatic Pruning} +\index[general]{Automatic Pruning} +\index[general]{Pruning!Automatic} + +As Bacula writes files to tape, it keeps a list of files, jobs, and volumes +in a database called the catalog. Among other things, the database helps +Bacula to decide which files to back up in an incremental or differential +backup, and helps you locate files on past backups when you want to restore +something. However, the catalog will grow larger and larger as time goes +on, and eventually it can become unacceptably large. + +Bacula's process for removing entries from the catalog is called Pruning. +The default is Automatic Pruning, which means that once an entry reaches a +certain age (e.g. 30 days old) it is removed from the catalog. Once a job +has been pruned, you can still restore it from the backup tape, but one +additional step is required: scanning the volume with bscan. The +alternative to Automatic Pruning is Manual Pruning, in which you explicitly +tell Bacula to erase the catalog entries for a volume. You'd usually do +this when you want to reuse a Bacula volume, because there's no point in +keeping a list of files that USED TO BE on a tape. Or, if the catalog is +starting to get too big, you could prune the oldest jobs to save space. +Manual pruning is done with the \ilink{ prune command}{ManualPruning} in +the console. (thanks to Bryce Denney for the above explanation). + +\section{Pruning Directives} +\index[general]{Pruning Directives } +\index[general]{Directives!Pruning } + +There are three pruning durations. All apply to catalog database records and +not to the actual data in a Volume. The pruning (or retention) durations are +for: Volumes (Media records), Jobs (Job records), and Files (File records). +The durations inter-depend a bit because if Bacula prunes a Volume, it +automatically removes all the Job records, and all the File records. Also when +a Job record is pruned, all the File records for that Job are also pruned +(deleted) from the catalog. + +Having the File records in the database means that you can examine all the +files backed up for a particular Job. They take the most space in the catalog +(probably 90-95\% of the total). When the File records are pruned, the Job +records can remain, and you can still examine what Jobs ran, but not the +details of the Files backed up. In addition, without the File records, you +cannot use the Console restore command to restore the files. + +When a Job record is pruned, the Volume (Media record) for that Job can still +remain in the database, and if you do a "list volumes", you will see the +volume information, but the Job records (and its File records) will no longer +be available. + +In each case, pruning removes information about where older files are, but it +also prevents the catalog from growing to be too large. You choose the +retention periods in function of how many files you are backing up and the +time periods you want to keep those records online, and the size of the +database. You can always re-insert the records (with 98\% of the original data) +by using "bscan" to scan in a whole Volume or any part of the volume that +you want. + +By setting {\bf AutoPrune} to {\bf yes} you will permit {\bf Bacula} to +automatically prune all Volumes in the Pool when a Job needs another Volume. +Volume pruning means removing records from the catalog. It does not shrink the +size of the Volume or affect the Volume data until the Volume gets +overwritten. When a Job requests another volume and there are no Volumes with +Volume Status {\bf Append} available, Bacula will begin volume pruning. This +means that all Jobs that are older than the {\bf VolumeRetention} period will +be pruned from every Volume that has Volume Status {\bf Full} or {\bf Used} +and has Recycle set to {\bf yes}. Pruning consists of deleting the +corresponding Job, File, and JobMedia records from the catalog database. No +change to the physical data on the Volume occurs during the pruning process. +When all files are pruned from a Volume (i.e. no records in the catalog), the +Volume will be marked as {\bf Purged} implying that no Jobs remain on the +volume. The Pool records that control the pruning are described below. + +\begin{description} + +\item [AutoPrune = \lt{}yes|no\gt{}] + \index[console]{AutoPrune } + If AutoPrune is set to {\bf yes} (default), Bacula + will automatically apply the Volume retention period when running a Job and + it needs a new Volume but no appendable volumes are available. At that point, + Bacula will prune all Volumes that can be pruned (i.e. AutoPrune set) in an + attempt to find a usable volume. If during the autoprune, all files are + pruned from the Volume, it will be marked with VolStatus {\bf Purged}. The + default is {\bf yes}. Note, that although the File and Job records may be + pruned from the catalog, a Volume will be marked Purged (and hence + ready for recycling) if the Volume status is Append, Full, Used, or Error. + If the Volume has another status, such as Archive, Read-Only, Disabled, + Busy, or Cleaning, the Volume status will not be changed to Purged. + +\item [Volume Retention = \lt{}time-period-specification\gt{}] + \index[console]{Volume Retention} + The Volume Retention record defines the length of time that Bacula will + guarantee that the Volume is not reused counting from the time the last + job stored on the Volume terminated. A key point is that this time + period is not even considered as long at the Volume remains appendable. + The Volume Retention period count down begins only when the Append + status has been changed to some othe status (Full, Used, Purged, ...). + + When this time period expires, and if {\bf AutoPrune} is set to {\bf + yes}, and a new Volume is needed, but no appendable Volume is available, + Bacula will prune (remove) Job records that are older than the specified + Volume Retention period. + + The Volume Retention period takes precedence over any Job Retention + period you have specified in the Client resource. It should also be + noted, that the Volume Retention period is obtained by reading the + Catalog Database Media record rather than the Pool resource record. + This means that if you change the VolumeRetention in the Pool resource + record, you must ensure that the corresponding change is made in the + catalog by using the {\bf update pool} command. Doing so will insure + that any new Volumes will be created with the changed Volume Retention + period. Any existing Volumes will have their own copy of the Volume + Retention period that can only be changed on a Volume by Volume basis + using the {\bf update volume} command. + + When all file catalog entries are removed from the volume, its VolStatus is + set to {\bf Purged}. The files remain physically on the Volume until the + volume is overwritten. + + Retention periods are specified in seconds, minutes, hours, days, weeks, + months, quarters, or years on the record. See the + \ilink{Configuration chapter}{Time} of this manual for + additional details of time specification. + +The default is 1 year. +% TODO: if that is the format, should it be in quotes? decide on a style + +\item [Recycle = \lt{}yes|no\gt{}] + \index[fd]{Recycle } + This statement tells Bacula whether or not the particular Volume can be + recycled (i.e. rewritten). If Recycle is set to {\bf no} (the + default), then even if Bacula prunes all the Jobs on the volume and it + is marked {\bf Purged}, it will not consider the tape for recycling. If + Recycle is set to {\bf yes} and all Jobs have been pruned, the volume + status will be set to {\bf Purged} and the volume may then be reused + when another volume is needed. If the volume is reused, it is relabeled + with the same Volume Name, however all previous data will be lost. + \end{description} + + It is also possible to "force" pruning of all Volumes in the Pool + associated with a Job by adding {\bf Prune Files = yes} to the Job resource. + +\label{Recycling} +\label{RecyclingAlgorithm} +\section{Recycling Algorithm} +\index[general]{Algorithm!Recycling } +\index[general]{Recycling Algorithm } + +After all Volumes of a Pool have been pruned (as mentioned above, this happens +when a Job needs a new Volume and no appendable Volumes are available), Bacula +will look for the oldest Volume that is Purged (all Jobs and Files expired), +and if the {\bf Recycle} flag is on (Recycle=yes) for that Volume, Bacula will +relabel it and write new data on it. + +As mentioned above, there are two key points for getting a Volume +to be recycled. First, the Volume must no longer be marked Append (there +are a number of directives to automatically make this change), and second +since the last write on the Volume, one or more of the Retention periods +must have expired so that there are no more catalog backup job records +that reference that Volume. Once both those conditions are satisfied, +the volume can be marked Purged and hence recycled. + +The full algorithm that Bacula uses when it needs a new Volume is: +\index[general]{New Volume Algorithm} +\index[general]{Algorithm!New Volume} + +The algorithm described below assumes that AutoPrune is enabled, +that Recycling is turned on, and that you have defined +appropriate Retention periods, or used the defaults for all these +items. + +\begin{itemize} +\item If the request is for an Autochanger device, look only + for Volumes in the Autochanger (i.e. with InChanger set and that have + the correct Storage device). +\item Search the Pool for a Volume with VolStatus=Append (if there is more + than one, the Volume with the oldest date last written is chosen. If + two have the same date then the one with the lowest MediaId is chosen). +\item Search the Pool for a Volume with VolStatus=Recycle and the InChanger + flag is set true (if there is more than one, the Volume with the oldest + date last written is chosen. If two have the same date then the one + with the lowest MediaId is chosen). +\item Try recycling any purged Volumes. +\item Prune volumes applying Volume retention period (Volumes with VolStatus + Full, Used, or Append are pruned). Note, even if all the File and Job + records are pruned from a Volume, the Volume will not be marked Purged + until the Volume retention period expires. +\item Search the Pool for a Volume with VolStatus=Purged +\item If a Pool named "Scratch" exists, search for a Volume and if found + move it to the current Pool for the Job and use it. Note, when + the Scratch Volume is moved into the current Pool, the basic + Pool defaults are applied as if it is a newly labeled Volume + (equivalent to an {\bf update volume from pool} command). +\item If we were looking for Volumes in the Autochanger, go back to + step 2 above, but this time, look for any Volume whether or not + it is in the Autochanger. +\item Attempt to create a new Volume if automatic labeling enabled + If Python is enabled, a Python NewVolume event is generated before + the Label Format directve is used. If the maximum number of Volumes + specified for the pool is reached, a new Volume will not be created. +\item Prune the oldest Volume if RecycleOldestVolume=yes (the Volume with the + oldest LastWritten date and VolStatus equal to Full, Recycle, Purged, Used, + or Append is chosen). This record ensures that all retention periods are + properly respected. +\item Purge the oldest Volume if PurgeOldestVolume=yes (the Volume with the + oldest LastWritten date and VolStatus equal to Full, Recycle, Purged, Used, + or Append is chosen). We strongly recommend against the use of {\bf + PurgeOldestVolume} as it can quite easily lead to loss of current backup + data. +\item Give up and ask operator. +\end{itemize} + +The above occurs when Bacula has finished writing a Volume or when no Volume +is present in the drive. + +On the other hand, if you have inserted a different Volume after the last job, +and Bacula recognizes the Volume as valid, it will request authorization from +the Director to use this Volume. In this case, if you have set {\bf Recycle +Current Volume = yes} and the Volume is marked as Used or Full, Bacula will +prune the volume and if all jobs were removed during the pruning (respecting +the retention periods), the Volume will be recycled and used. + +The recycling algorithm in this case is: +\begin{itemize} +\item If the VolStatus is {\bf Append} or {\bf Recycle} + is set, the volume will be used. +\item If {\bf Recycle Current Volume} is set and the volume is marked {\bf + Full} or {\bf Used}, Bacula will prune the volume (applying the retention + period). If all Jobs are pruned from the volume, it will be recycled. +\end{itemize} + +This permits users to manually change the Volume every day and load tapes in +an order different from what is in the catalog, and if the volume does not +contain a current copy of your backup data, it will be used. + +A few points from Alan Brown to keep in mind: + +\begin{enumerate} +\item If a pool doesn't have maximum volumes defined then Bacula will prefer to + demand new volumes over forcibly purging older volumes. + +\item If volumes become free through pruning and the Volume retention period has + expired, then they get marked as "purged" and are immediately available for + recycling - these will be used in preference to creating new volumes. + +\item If the Job, File, and Volume retention periods are different, then + it's common to see a tape with no files or jobs listed in the database, + but which is still not marked as "purged". +\end{enumerate} + + +\section{Recycle Status} +\index[general]{Status!Recycle } +\index[general]{Recycle Status } + +Each Volume inherits the Recycle status (yes or no) from the Pool resource +record when the Media record is created (normally when the Volume is labeled). +This Recycle status is stored in the Media record of the Catalog. Using +the Console program, you may subsequently change the Recycle status for each +Volume. For example in the following output from {\bf list volumes}: + +\footnotesize +\begin{verbatim} ++----------+-------+--------+---------+------------+--------+-----+ +| VolumeNa | Media | VolSta | VolByte | LastWritte | VolRet | Rec | ++----------+-------+--------+---------+------------+--------+-----+ +| File0001 | File | Full | 4190055 | 2002-05-25 | 14400 | 1 | +| File0002 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0003 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0004 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0005 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0006 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0007 | File | Purged | 1896466 | 2002-05-26 | 14400 | 1 | ++----------+-------+--------+---------+------------+--------+-----+ +\end{verbatim} +\normalsize + +all the volumes are marked as recyclable, and the last Volume, {\bf File0007} +has been purged, so it may be immediately recycled. The other volumes are all +marked recyclable and when their Volume Retention period (14400 seconds or four +hours) expires, they will be eligible for pruning, and possibly recycling. +Even though Volume {\bf File0007} has been purged, all the data on the Volume +is still recoverable. A purged Volume simply means that there are no entries +in the Catalog. Even if the Volume Status is changed to {\bf Recycle}, the +data on the Volume will be recoverable. The data is lost only when the Volume +is re-labeled and re-written. + +To modify Volume {\bf File0001} so that it cannot be recycled, you use the +{\bf update volume pool=File} command in the console program, or simply {\bf +update} and Bacula will prompt you for the information. + +\footnotesize +\begin{verbatim} ++----------+------+-------+---------+-------------+-------+-----+ +| VolumeNa | Media| VolSta| VolByte | LastWritten | VolRet| Rec | ++----------+------+-------+---------+-------------+-------+-----+ +| File0001 | File | Full | 4190055 | 2002-05-25 | 14400 | 0 | +| File0002 | File | Full | 1897236 | 2002-05-26 | 14400 | 1 | +| File0003 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0004 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0005 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0006 | File | Full | 1896460 | 2002-05-26 | 14400 | 1 | +| File0007 | File | Purged| 1896466 | 2002-05-26 | 14400 | 1 | ++----------+------+-------+---------+-------------+-------+-----+ +\end{verbatim} +\normalsize + +In this case, {\bf File0001} will never be automatically recycled. The same +effect can be achieved by setting the Volume Status to Read-Only. + +As you have noted, the Volume Status (VolStatus) column in the +catalog database contains the current status of the Volume, which +is normally maintained automatically by Bacula. To give you an +idea of some of the values it can take during the life cycle of +a Volume, here is a picture created by Arno Lehmann: + +\footnotesize +\begin{verbatim} +A typical volume life cycle is like this: + + because job count or size limit exceeded + Append ----------------------------------------> Used + ^ | + | First Job writes to Retention time passed | + | the volume and recycling takes | + | place | + | v + Recycled <-------------------------------------- Purged + Volume is selected for reuse + +\end{verbatim} +\normalsize + + +\section{Making Bacula Use a Single Tape} +\label{singletape} +\index[general]{Tape!Making Bacula Use a Single} +\index[general]{Making Bacula Use a Single Tape} + +Most people will want Bacula to fill a tape and when it is full, a new tape +will be mounted, and so on. However, as an extreme example, it is possible for +Bacula to write on a single tape, and every night to rewrite it. To get this +to work, you must do two things: first, set the VolumeRetention to less than +your save period (one day), and the second item is to make Bacula mark the +tape as full after using it once. This is done using {\bf UseVolumeOnce = +yes}. If this latter record is not used and the tape is not full after the +first time it is written, Bacula will simply append to the tape and eventually +request another volume. Using the tape only once, forces the tape to be marked +{\bf Full} after each use, and the next time {\bf Bacula} runs, it will +recycle the tape. + +An example Pool resource that does this is: + +\footnotesize +\begin{verbatim} +Pool { + Name = DDS-4 + Use Volume Once = yes + Pool Type = Backup + AutoPrune = yes + VolumeRetention = 12h # expire after 12 hours + Recycle = yes +} +\end{verbatim} +\normalsize + +\section{Daily, Weekly, Monthly Tape Usage Example} +\label{usageexample} +\index[general]{Daily, Weekly, Monthly Tape Usage Example } +\index[general]{Example!Daily Weekly Monthly Tape Usage } + +This example is meant to show you how one could define a fixed set of volumes +that Bacula will rotate through on a regular schedule. There are an infinite +number of such schemes, all of which have various advantages and +disadvantages. + +We start with the following assumptions: + +\begin{itemize} +\item A single tape has more than enough capacity to do a full save. +\item There are ten tapes that are used on a daily basis for incremental + backups. They are prelabeled Daily1 ... Daily10. +\item There are four tapes that are used on a weekly basis for full backups. + They are labeled Week1 ... Week4. +\item There are 12 tapes that are used on a monthly basis for full backups. + They are numbered Month1 ... Month12 +\item A full backup is done every Saturday evening (tape inserted Friday + evening before leaving work). +\item No backups are done over the weekend (this is easy to change). +\item The first Friday of each month, a Monthly tape is used for the Full + backup. +\item Incremental backups are done Monday - Friday (actually Tue-Fri + mornings). +% TODO: why this "actually"? does this need to be explained? + \end{itemize} + +We start the system by doing a Full save to one of the weekly volumes or one +of the monthly volumes. The next morning, we remove the tape and insert a +Daily tape. Friday evening, we remove the Daily tape and insert the next tape +in the Weekly series. Monday, we remove the Weekly tape and re-insert the +Daily tape. On the first Friday of the next month, we insert the next Monthly +tape in the series rather than a Weekly tape, then continue. When a Daily tape +finally fills up, {\bf Bacula} will request the next one in the series, and +the next day when you notice the email message, you will mount it and {\bf +Bacula} will finish the unfinished incremental backup. + +What does this give? Well, at any point, you will have the last complete +Full save plus several Incremental saves. For any given file you want to +recover (or your whole system), you will have a copy of that file every day +for at least the last 14 days. For older versions, you will have at least three +and probably four Friday full saves of that file, and going back further, you +will have a copy of that file made on the beginning of the month for at least +a year. + +So you have copies of any file (or your whole system) for at least a year, but +as you go back in time, the time between copies increases from daily to weekly +to monthly. + +What would the Bacula configuration look like to implement such a scheme? + +\footnotesize +\begin{verbatim} +Schedule { + Name = "NightlySave" + Run = Level=Full Pool=Monthly 1st sat at 03:05 + Run = Level=Full Pool=Weekly 2nd-5th sat at 03:05 + Run = Level=Incremental Pool=Daily tue-fri at 03:05 +} +Job { + Name = "NightlySave" + Type = Backup + Level = Full + Client = LocalMachine + FileSet = "File Set" + Messages = Standard + Storage = DDS-4 + Pool = Daily + Schedule = "NightlySave" +} +# Definition of file storage device +Storage { + Name = DDS-4 + Address = localhost + SDPort = 9103 + Password = XXXXXXXXXXXXX + Device = FileStorage + Media Type = 8mm +} +FileSet { + Name = "File Set" + Include = signature=MD5 { + fffffffffffffffff + } + Exclude = { *.o } +} +Pool { + Name = Daily + Pool Type = Backup + AutoPrune = yes + VolumeRetention = 10d # recycle in 10 days + Maximum Volumes = 10 + Recycle = yes +} +Pool { + Name = Weekly + Use Volume Once = yes + Pool Type = Backup + AutoPrune = yes + VolumeRetention = 30d # recycle in 30 days (default) + Recycle = yes +} +Pool { + Name = Monthly + Use Volume Once = yes + Pool Type = Backup + AutoPrune = yes + VolumeRetention = 365d # recycle in 1 year + Recycle = yes +} +\end{verbatim} +\normalsize + +\section{ Automatic Pruning and Recycling Example} +\label{PruningExample} +\index[general]{Automatic Pruning and Recycling Example } +\index[general]{Example!Automatic Pruning and Recycling } + +Perhaps the best way to understand the various resource records that come into +play during automatic pruning and recycling is to run a Job that goes through +the whole cycle. If you add the following resources to your Director's +configuration file: + +\footnotesize +\begin{verbatim} +Schedule { + Name = "30 minute cycle" + Run = Level=Full Pool=File Messages=Standard Storage=File + hourly at 0:05 + Run = Level=Full Pool=File Messages=Standard Storage=File + hourly at 0:35 +} +Job { + Name = "Filetest" + Type = Backup + Level = Full + Client=XXXXXXXXXX + FileSet="Test Files" + Messages = Standard + Storage = File + Pool = File + Schedule = "30 minute cycle" +} +# Definition of file storage device +Storage { + Name = File + Address = XXXXXXXXXXX + SDPort = 9103 + Password = XXXXXXXXXXXXX + Device = FileStorage + Media Type = File +} +FileSet { + Name = "Test Files" + Include = signature=MD5 { + fffffffffffffffff + } + Exclude = { *.o } +} +Pool { + Name = File + Use Volume Once = yes + Pool Type = Backup + LabelFormat = "File" + AutoPrune = yes + VolumeRetention = 4h + Maximum Volumes = 12 + Recycle = yes +} +\end{verbatim} +\normalsize + +Where you will need to replace the {\bf ffffffffff}'s by the appropriate files +to be saved for your configuration. For the FileSet Include, choose a +directory that has one or two megabytes maximum since there will probably be +approximately eight copies of the directory that {\bf Bacula} will cycle through. + +In addition, you will need to add the following to your Storage daemon's +configuration file: + +\footnotesize +\begin{verbatim} +Device { + Name = FileStorage + Media Type = File + Archive Device = /tmp + LabelMedia = yes; + Random Access = Yes; + AutomaticMount = yes; + RemovableMedia = no; + AlwaysOpen = no; +} +\end{verbatim} +\normalsize + +With the above resources, Bacula will start a Job every half hour that saves a +copy of the directory you chose to /tmp/File0001 ... /tmp/File0012. After 4 +hours, Bacula will start recycling the backup Volumes (/tmp/File0001 ...). You +should see this happening in the output produced. Bacula will automatically +create the Volumes (Files) the first time it uses them. + +To turn it off, either delete all the resources you've added, or simply +comment out the {\bf Schedule} record in the {\bf Job} resource. + +\section{Manually Recycling Volumes} +\label{manualrecycling} +\index[general]{Volumes!Manually Recycling } +\index[general]{Manually Recycling Volumes } + +Although automatic recycling of Volumes is implemented in version 1.20 and +later (see the +\ilink{Automatic Recycling of Volumes}{RecyclingChapter} chapter of +this manual), you may want to manually force reuse (recycling) of a Volume. + +Assuming that you want to keep the Volume name, but you simply want to write +new data on the tape, the steps to take are: + +\begin{itemize} +\item Use the {\bf update volume} command in the Console to ensure that the + {\bf Recycle} field is set to {\bf 1} +\item Use the {\bf purge jobs volume} command in the Console to mark the + Volume as {\bf Purged}. Check by using {\bf list volumes}. +\end{itemize} + +Once the Volume is marked Purged, it will be recycled the next time a Volume +is needed. + +If you wish to reuse the tape by giving it a new name, follow the following +steps: + +\begin{itemize} +\item Use the {\bf purge jobs volume} command in the Console to mark the + Volume as {\bf Purged}. Check by using {\bf list volumes}. +\item In Bacula version 1.30 or greater, use the Console {\bf relabel} + command to relabel the Volume. +\end{itemize} + +Please note that the relabel command applies only to tape Volumes. + +For Bacula versions prior to 1.30 or to manually relabel the Volume, use the +instructions below: + +\begin{itemize} +\item Use the {\bf delete volume} command in the Console to delete the Volume + from the Catalog. +\item If a different tape is mounted, use the {\bf unmount} command, + remove the tape, and insert the tape to be renamed. +\item Write an EOF mark in the tape using the following commands: + +\footnotesize +\begin{verbatim} + mt -f /dev/nst0 rewind + mt -f /dev/nst0 weof +\end{verbatim} +\normalsize + +where you replace {\bf /dev/nst0} with the appropriate device name on your +system. +\item Use the {\bf label} command to write a new label to the tape and to + enter it in the catalog. +\end{itemize} + +Please be aware that the {\bf delete} command can be dangerous. Once it is +done, to recover the File records, you must either restore your database as it +was before the {\bf delete} command, or use the {\bf bscan} utility program to +scan the tape and recreate the database entries. diff --git a/docs/manuals/fr/concepts/requirements.tex b/docs/manuals/fr/concepts/requirements.tex new file mode 100644 index 00000000..e720635f --- /dev/null +++ b/docs/manuals/fr/concepts/requirements.tex @@ -0,0 +1,63 @@ +%% +%% + +\chapter{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula} +\label{_ChapterStart51} +\index[general]{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula } +\index[general]{Bacula!Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a } +\addcontentsline{toc}{section}{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula} + +\label{SysReqs} + +\section{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula} +\index[general]{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula } +\index[general]{Bacula!Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a } +\addcontentsline{toc}{section}{Caract\'eristiques syst\`eme g\'en\'erales indispensables \`a Bacula} + +\begin{itemize} +\item {\bf Bacula} a \'et\'e compil\'e et ex\'ecut\'e sur les syst\`emes + Linux RedHat, Mandriva, SUSE, Debian et Gentoo, sur FreeBSD, et Solaris. +\item Il requiert GNU C++ version 2.95 ou sup\'erieur pour compiler. Vous + pouvez essayer avec d'autres compilateurs et des versions plus anciennes, mais + vous serez seuls. Nous avons compil\'e et utilis\'e avec succ\`es Bacula sur +RH8.0/RH9/RHEL 3.0 avec GCC 3.2. Note, en g\'en\'eral GNU C++ est un paquet +s\'epar\'e (e.g. RPM) de GNU C, et vous devrez avoir les deux. Sur les +syst\`emes RedHat, le compilateur C++ fait partie du paquet RPM {\bf +gcc-c++}. +\item Certains paquets tiers sont n\'ecessaires \`a {\bf Bacula}. + Except\'e pour MySQL et PostgreSQL, ils peuvent tous \^etre trouv\'es dans + les distributions {\bf depkgs} et {\bf depkgs1}. +\item Si vous voulez construire les binaires Win32, vous aurez besoin du + compilateur Microsoft Visual C++ (ou Visual Studio). Bien que tous les + composants compilent (la console produit quelques messages d'alertes), seul +le File Daemon a \'et\'e test\'e. +\item {\bf Bacula} requiert une bonne impl\'ementation fonctionnelle des + pthreads. Ce n'est pas le cas sur certains syst\`emes BSD. +\item Le code source a \'et\'e \'ecrit dans un esprit de portabilit\'e et est + le plus souvent compatible POSIX. Ainsi le portage sur chaque syst\`eme + d'exploitation compatible POSIX est relativement ais\'e. +\item Le programme GNOME Console est developp\'e et test\'e sous GNOME 2.X. + Il s'ex\'ecute aussi sous GNOME 1.4 mais cette version est d\'epr\'eci\'ee et + n'est plus maintenue. +\item Le programme wxWidgets Console est developp\'e et test\'e avec la + derni\`ere version stable de + \elink{ wxWidgets}{http://www.wxwidgets.org/} (2.4.2). Il fonctionne bien +avec la version Windows et GTK+-1.x de wxWidgets, ainsi que sur les autres +plateformes support\'ees par wxWidgets. +\item Le programme Tray Monitor est developp\'e pour GTK+-2.x. Il n\'ecessite + Gnome \gt{}=2.2, KDE \gt{}=3.1 ou un gestionnaire de fen\^etre supportant le + standard +\elink{systemtray}{http://www.freedesktop.org/Standards/systemtray-spec} de +FreeDesktop. +\item Si vous voulez permettre l'\'edition en ligne de commande et + l'historique, il vous faudra /usr/include/termcap.h et l'une des + biblioth\`eques termcap ou ncurses charg\'ee (libtermcap-devel ou +ncurses-devel). +\item Si vous voulez utiliser des DVD en guise de media de sauvegarde, vous devrez + t\'el\'echarger les \elink{dvd+rw-tools 5.21.4.10.8}{http://fy.chalmers.se/~appro/linux/DVD+RW/}, + appliquer le \elink{patch}{http://cvs.sourceforge.net/viewcvs.py/*checkout*/bacula/bacula/patches/dvd+rw-tools-5.21.4.10.8.bacula.patch} + pour rendre ces outils compatibles avec Bacula, puis les compiler et installer. + N'utilisez pas les dvd+rw-tools fournis par votre distribution, ils ne + fonctionneront pas avec Bacula. + +\end{itemize} diff --git a/docs/manuals/fr/concepts/restore.tex b/docs/manuals/fr/concepts/restore.tex new file mode 100644 index 00000000..ea232f24 --- /dev/null +++ b/docs/manuals/fr/concepts/restore.tex @@ -0,0 +1,1209 @@ +%% +%% + +\chapter{La commande restore de la console Bacula} +\label{_ChapterStart13} +\index[general]{Commande!restore de la console Bacula} +\index[general]{La commande restore de la console Bacula} +\addcontentsline{toc}{section}{La commande restore de la console Bacula} + +\section{G\'en\'eralit\'es} +\index[general]{G\'en\'eralit\'es} +\addcontentsline{toc}{section}{G\'en\'eralit\'es} + +Nous allons maintenant d\'ecrire la restauration de fichiers avec la commande +{\bf restore} de la Console, qui est le mode de restauration recommand\'e. +Il existe cependant un programme ind\'ependant nomm\'e {\bf bextract}, qui permet +lui aussi de restaurer des fichiers. Pour plus d'informations sur ce +programme, consultez le chapitre \ilink{Programmes utilitaires Bacula}{bextract} +de ce manuel. Vous y trouverez aussi des informations sur le programme {\bf bls} +qui sert \`a produire une liste du contenu de vos volumes, et sur le programme +{\bf bscan} qui vous sera utilie si vous voulez restaurer les enregistrements +du catalogue relatifs \`a un ancien volume qui n'y figure plus. + +En g\'en\'eral, pour restaurer un fichier ou un ensemble de fichiers, vous devez +ex\'ecuter un job de type {\bf restore}, par cons\'equent, vous devez pr\'ed\'efinir +un tel job dans le fichier de configuration de votre Director. Les param\`etres +(Client, FileSet,...) que vous d\'efinissez ici ne sont pas importants, +Bacula les ajustera automatiquement lors de l'utilisation de {\bf restore}. + +Bacula \'etant un programme r\'eseau, il vous appartient de vous assurer que +vous avez s\'electionn\'e le bon client et le bon disque dur pour recevoir la +restauration. Bacula peut sauvegarder le client A et restaurer ses fichiers +sur le client B, pourvu que leurs syst\`emes ne soient pas trop diff\'erents +au niveau de leurs structures de fichiers. Par d\'efaut, Bacula restaure les +donn\'ees sur leur client d'origine, mais pas \`a leur emplacement d'origine : +dans le r\'epertoire {\bf /tmp/bacula-restores}. Vous pouvez modifier ces +valeurs par d\'efaut lorsque la commande {\bf restore} vous demande confirmation +d'ex\'ecution du job en choisissant l'option {\bf mod}. + +\label{Example1} +\section{La commande Restore} +\index[general]{Commande!Restore } +\index[general]{La commande Restore} +\addcontentsline{toc}{section}{La commande Restore} +Puisque Bacula maintient un catalogue des fichiers sauvegard\'es, et des volumes +o\`u ils sont stock\'es, il peut se charger de la majeure partie du travail +d'intendance. Ainsi, il vous suffit de sp\'ecifier le type de restauration que +vous souhaitez (d'apr\`es la derni\`ere sauvegarde, d'apr\`es la derni\`ere sauvegarde +ant\'erieure \`a une date sp\'ecifi\'ee...), et quels fichiers vous voulez restaurer. + +Ceci est r\'ealis\'e par la commande {\bf restore} de la Console. Vous s\'electionnez +d'abord le type de restauration souhait\'ee ce qui entra\^ine la s\'election des +JobIds requis et la construction d'une arborescence interne \`a Bacula contenant +les enregistrements de fichiers des JobIds s\'electionn\'es. A ce stade, le +processus de restauration entre dans un mode o\`u vous pouvez naviguer +interactivement dans l'arborescence des fichiers disponibles pour restauration +et s\'electionner ceux que vous voulez restaurer. Ce mode est similaire au +programme de s\'election de fichier interactif standard d'Unix {\bf restore}. + +Si vos fichiers ont \'et\'e \'elagu\'es, la commande {\bf restore} sera dans +l'incapacit\'e de les trouver. Voyez ci-dessous pour plus de d\'etails sur ce cas +de figure. + +Dans la Console, apr\`es avoir saisi {\bf restore}, le menu suivant vous est +pr\'esent\'e : + +\footnotesize +\begin{verbatim} +First you select one or more JobIds that contain files +to be restored. You will be presented several methods +of specifying the JobIds. Then you will be allowed to +select which files from those JobIds are to be restored. +To select the JobIds, you have the following choices: + 1: List last 20 Jobs run + 2: List Jobs where a given File is saved + 3: Enter list of comma separated JobIds to select + 4: Enter SQL list command + 5: Select the most recent backup for a client + 6: Select backup for a client before a specified time + 7: Enter a list of files to restore + 8: Enter a list of files to restore before a specified time + 9: Find the JobIds of the most recent backup for a client + 10: Find the JobIds for a backup for a client before a specified time + 11: Enter a list of directories to restore for found JobIds + 12: Cancel +Select item: (1-12): +\end{verbatim} +\normalsize + +\begin{itemize} +\item Le choix 1 \'enum\`ere les 20 derniers jobs ex\'ecut\'es. Si vous trouvez + celui (ceux) que vous voulez, vous pouvez ensuite faire le choix 3 et entrer + son (leurs) JobId(s). + +\item Le choix 2 affiche tous les Jobs ayant sauvegard\'e un fichier + sp\'ecifi\'e. Si vous trouvez celui (ceux) que vous voulez, vous pouvez ensuite + faire le choix 3 et entrer son (leurs) JobId(s). + +\item Le choix 3 vous permet de saisir une liste de JobIds, s\'epar\'es par des + virgules. Les fichiers de ces jobs seront plac\'es dans l'arborescence afin + que vous puissiez s\'electionner ceux que vous voulez restaurer. + +\item Le choix 4 vous permet d'entrer une requ\^ete SQL arbitraire. C'est + certainement le moyen le plus primitif pour trouver les jobs d\'esir\'es, + mais aussi le plus flexible. Si vous trouvez celui (ceux) que vous voulez, + vous pouvez ensuite faire le choix 3 et entrer son (leurs) JobId(s). + +\item Le choix 5 s\'electionne automatiquement la full la plus r\'ecente, et toutes + les incr\'ementales et diff\'erentielles subs\'equentes \`a cette full pour un + client sp\'ecifi\'e. Il s'agit l\`a des jobs et fichiers qui, si vous les + restaurez, ram\`eneront votre syst\`eme \`a son dernier \'etat sauvegard\'e. + Les JobIds sont automatiquement charg\'es dans l'arborescence. C'est + probablement le plus pratique des choix propos\'es pour restaurer un + client \`a son \'etat le plus r\'ecent. + + Notez que ce processus de s\'election automatique ne s\'electionnera jamais + un job qui a \'echou\'e (termin\'e avec un statut d'erreur). Si vous disposez + d'un tel job dont vous voulez extraire des fichiers, vous devez + eplicitement entrer son JobId au niveau du choix 3 et choisir les fichiers + \`a restaurer. + + Si certains de jobs requis pour la restauration ont eu leurs enregistrements + de fichiers \'elagu\'es, la restauration sera incompl\`ete. Bacula ne d\'etecte + pas, pour l'instant, cette condition. Vous pouvez cependant la + contr\^oler en examinant attentivement la liste des jobs s\'electionn\'es + et affich\'es par Bacula. Si vous trouvez des jobs dont le champ JobFiles + est \`a z\'ero alors que ces fichiers auraient d\^u \^etre sauvegard\'es, alors + vous pouvez vous attendre \`a des probl\`emes. + + Si tous les enregistrements de fichiers ont \'et\'e \'elagu\'es, Bacula constatera + qu'il n'y a aucune r\'ef\'erence \`a aucun fichier pour le JobIds s\'electionn\'es + et vous en informera, et vous proposera de faire une restauration compl\`ete + (non s\'elective) de ces JobIds. Ceci est possible car Bacula sait encore + o\`u commencent les donn\'ees sur les volumes, m\^eme s'il ne sait plus o\`u sont + les fichiers individuellement. + +\item Le choix 6 vous permet de sp\'ecifier une date et un heure. Bacula + s\'electionne alors automatiquement la plus r\'ecente full ant\'erieure \`a cette date + ainsi que les incr\'ementales et diff\'erentielles subs\'equentes \`a cette full et + ant\'erieures \`a cette date. + +\item Le choix 7 vous permet de sp\'ecifier un ou plusieurs noms de fichiers + (le chemin absolu est requis) \`a restaurer. Les noms de fichiers sont saisis + un par un, \`a moins que vous ne pr\'ef\'eriez cr\'eer un fichier pr\'efix\'e du + caract\`ere "moins" (\lt{}) que Bacula consid\`ere comme une liste de fichier + \`a restaurer. Pour quitter ce mode, entrez une ligne vide. + +\item Le choix 8 vous permet de sp\'ecifier une date et une heure avant + d'entrer les noms de fichiers. Voir le choix 7 pour plus de d\'etails. + +\item Le choix 9 vous permet de d\'eterminer les JobIds de la sauvegarde + la plus r\'ecente pour un client. C'est essentiellement la m\^eme chose + que le choix 5 (le m\^eme code est utilis\'e), mais ces JobIds sont + conserv\'es en interne comme si vous les aviez saisis manuellement. + Vous pouvez alors faire le choix 11 pour restaurer un ou plusieurs + r\'epertoires. + +\item Le choix 10 est le m\^eme que le 9, sauf qu'il vous permet d'entrer + une date butoir (comme pour le choix 6) pour la s\'election des JobIds. + Ces JobIds sont conserv\'es en interne comme si vous les aviez saisis manuellement. + +\index[general]{Restaurer des r\'epertoires} +\item Le choix 11 vous permet d'entrer une liste de JobIds \`a partir de + laquelle vous pouvez s\'electionner les r\'epertoires \`a restaurer. La liste de + JobIds peut avoir \'et\'e \'etablie pr\'ec\'edemment \`a l'aide des choix 9 ou 10 + du menu. Vous pouvez alors entrer le chemin absolu d'un r\'epertoire, ou + un nom de fichier pr\'efix\'e d'un signe "moins" (\lt{}) contenant la liste + des r\'epertoires \`a restaurer. Tous les fichiers des r\'epertoires s\'electionn\'es + seront restaur\'es, mais pas les sous-r\'epertoires, \`a moins que vous ne les + sp\'ecifiiez explicitement. + +\item Le choix 12 vous permet d'abandonner la restauration. +\end{itemize} + +A titre d'exemple, supposons que nous s\'electionnions l'option 5 (restaurer \`a +l'\'etat le plus r\'ecent). Bacula vous demande alors le client d\'esir\'e ce qui, +sur mon syst\`eme, se manifeste ainsi : + +\footnotesize +\begin{verbatim} +Defined clients: + 1: Rufus + 2: Matou + 3: Polymatou + 4: Minimatou + 5: Minou + 6: MatouVerify + 7: PmatouVerify + 8: RufusVerify + 9: Watchdog +Select Client (File daemon) resource (1-9): + +\end{verbatim} +\normalsize + +Si vous n'avez qu'un client, il est automatiquement s\'electionn\'e. Dans le cas +pr\'esent, j'entre {\bf Rufus} pour s\'electionner ce client. Bacula a +maintenant conna\^itre le FileSet \`a restaurer, aussi il affiche : + +\footnotesize +\begin{verbatim} +The defined FileSet resources are: + 1: Full Set + 2: Kerns Files +Select FileSet resource (1-2): + +\end{verbatim} +\normalsize + +J'opte pour le choix 1, ma sauvegarde full. En principe, vous n'aurez qu'un +FileSet pour chaque job, et si vos machines de ressemblent (m\^emes syst\`emes), +vous pouvez n'avoir qu'un seul FileSet pour tous vos clients. + +A ce stade, Bacula d\'etient toutes les informations dont il a besoin pour +trouver le jeu de sauvegardes le plus r\'ecent. Il va maintenant interroger le +cataloguie, ce qui peut prendre un peu de temps, et afficher quelque chose +comme : + +\footnotesize +\begin{verbatim} ++-------+------+----------+-------------+-------------+------+-------+---------- +--+ +| JobId | Levl | JobFiles | StartTime | VolumeName | File | SesId | +VolSesTime | ++-------+------+----------+-------------+-------------+------+-------+---------- +--+ +| 1,792 | F | 128,374 | 08-03 01:58 | DLT-19Jul02 | 67 | 18 | +1028042998 | +| 1,792 | F | 128,374 | 08-03 01:58 | DLT-04Aug02 | 0 | 18 | +1028042998 | +| 1,797 | I | 254 | 08-04 13:53 | DLT-04Aug02 | 5 | 23 | +1028042998 | +| 1,798 | I | 15 | 08-05 01:05 | DLT-04Aug02 | 6 | 24 | +1028042998 | ++-------+------+----------+-------------+-------------+------+-------+---------- +--+ +You have selected the following JobId: 1792,1792,1797 +Building directory tree for JobId 1792 ... +Building directory tree for JobId 1797 ... +Building directory tree for JobId 1798 ... +cwd is: / +$ +\end{verbatim} +\normalsize + +(Certaines colonnes sont tromqu\'ees pour des n\'ecessit\'es de mise en page). + +Selon le nombre de {\bf JobFiles} pour chaque JobId, la construction de +l'arborescence peut prendre un certain temps. Si vous constatez que tous les +JobFiles sont \`a z\'ero, vos fichiers ont probalement \'et\'e \'elagu\'es et vous ne +pourrez pas s\'electionner les fichiers individuellement : vous devrez +restaurer tout ou rien. + +Dans notre exemple, Bacula a trouv\'e quatre jobs qui comprennent la +sauvegarde la plus r\'ecente du client et du FileSet sp\'ecifi\'es. Deux des jobs +ont le m\^eme JobId car le job a \'ecrit sur deux volumes diff\'erents. Le +troisi\`eme est une incr\'ementale qui n'a sauvegard\'e que 254 fichier sur les +128 374 de la full. Le quatri\`eme est aussi une incr\'ementale, et n'a sauvegard\'e +que 15 fichiers. + +Maintenant Bacula ins\`ere ces jobs dans l'arborescence, sans en marquer aucun +pour restauration par d\'efaut. Il vous indique le nombre de fichiers dans +l'arbre, et vous informe que le r\'epertoire de travail courant ({\bf cwd}) est +/. Finalement, Bacula vous invite avec le signe (\$) \`a saisir des commandes +pour vous d\'eplacer dans l'arborescence, et s\'electionner des fichiers. + +Si vous voulez que tous les fichiers de l'arbre soient marqu\'es pour +restauration \`a sa construction, tapez {\bf restore all}. + +Plut\^ot que de choisir l'option 5 du premier menu (s\'electionner la +sauvegarde la plus r\'ecente pour un client), si nous avions choisi l'option 3 +(Entrer une liste de JobIds \`a s\'electionner), et si nous avions saisi +{\bf 1792,1797,1798}, nous serions arriv\'es au m\^eme point. + +Il faut noter un point si vous saisissez manuellement les JobIds : vous devez +les entrer dans l'ordre o\`u ils ont \'et\'e ex\'ecut\'es (en g\'en\'eral, l'ordre croissant. +Si vous les sasissez dans un ordre diff\'erent, vous courrez le risque de ne pas +version la plus r\'ecente d'un fichier sauvegard\'e plusieurs fois si celui-ci a \'et\'e +sauvegard\'e dans plusieurs jobs. + +Entre vos JobIds directement peut aussi vous permettre de restaurer depuis +un job qui a \'ecrit des donn\'ees sur les volumes mais qui s'est termin\'e en erreur. + +Dans le mode s\'election de fichiers, vous pouvez utiliser {\bf help} ou une +question (?) pour produire un r\'esum\'e des commandes disponibles : + +\footnotesize +\begin{verbatim} + Command Description + ======= =========== + cd change current directory + count count marked files in and below the cd + dir long list current directory, wildcards allowed + done leave file selection mode + estimate estimate restore size + exit same as done command + find find files, wildcards allowed + help print help + ls list current directory, wildcards allowed + lsmark list the marked files in and below the cd + mark mark dir/file to be restored recursively in dirs + markdir mark directory name to be restored (no files) + pwd print current working directory + unmark unmark dir/file to be restored recursively in dir + unmarkdir unmark directory name only no recursion + quit quit and do not do restore + ? print help +\end{verbatim} +\normalsize + +Par d\'efaut, aucun fichier n'est s\'electionn\'e pour restauration (sauf si vous +avez ajout\'e {\bf all} \`a la ligne de commande). Si, \`a ce stade, vous voulez +tout restaurer, vous devriez saisir {\bf mark *}, puis {\bf done}, Bacula +\'ecrira alors les donn\'ees bootstrap dans un fichier et sollicitera votre +approbation pour d\'emarrer la restauration. + +Si vous n'utilisez pas {\bf mark *}, vous commencez avec une s\'election vide. +Vous pouvez simplement regarder et marquer ({\bf mark}) les fichiers et/ou +r\'epertoires qui vous int\'eressent. Il est ais\'e de commettre une erreur dans ces +op\'erations, et la gestion des erreurs dans Bacula n'est pas parfaite, aussi +contr\^olez votre travail avec la commande {\bf ls} ou {\bf dir} pour voir +quels fichiers ont \'et\'e s\'electionn\'es. Les fichiers s\'electionn\'es sont pr\'ec\'ed\'es +d'une ast\'erisque. + +Pour contr\^oler ce qui est marqu\'e et ce qui ne l'est pas utilisez la commande +{\bf count} qui affiche : + +\footnotesize +\begin{verbatim} +128401 total files. 128401 marked to be restored. + +\end{verbatim} +\normalsize + +Chacune des commandes ci-dessus sera expliqu\'e plus en d\'etail dans la +prochaine section. Poursuivons avec notre exemple, en validant la restauration de +tous les fichiers. En saisissant {\bf done}, Bacula affiche : + +\footnotesize +\begin{verbatim} +Bootstrap records written to /home/kern/bacula/working/restore.bsr +The restore job will require the following Volumes: + + DLT-19Jul02 + DLT-04Aug02 +128401 files selected to restore. +Run Restore job +JobName: kernsrestore +Bootstrap: /home/kern/bacula/working/restore.bsr +Where: /tmp/bacula-restores +Replace: always +FileSet: Kerns Files +Client: Rufus +Storage: SDT-10000 +JobId: *None* +OK to run? (yes/mod/no): + +\end{verbatim} +\normalsize + +Examinez chaque \'el\'ement attentivement pour vous assurer que tout est +conforme \`a ce que vous souhaitez. En particulier, v\'erifiez la ligne {\bf where}, +qui vous indique dans quelle partie du syst\`eme de fichiers vos donn\'ees +seront restaur\'ees, et quel client va les recevoir (par d\'efaut, les +restaurations ont lieu sur le client d'origine). Ces param\`etres n'auront pas +forc\'ement les bonnes valeurs, mais vous pouvez les modifier \`a l'aide +de la commande {\bf mod} et en vous laissant guider par l'invite de la +console. + +L'affichage ci-dessus suppose que vous ayez d\'efini une ressource Job de type +{\bf restore} dans le fichier de configuration de votre Director. en +principe, vous n'en n'aurez besoin que d'une, car, par nature, une +restauration est une op\'eration essentiellement manuelle. A l'aide de la +Console, vous pourrez modifier le job Restore pour faire ce que vous voulez +qu'il fasse. + +Un exemple de ressource Job de type restore est donn\'e plus bas. + +Pour en revenir \`a notre exemple, en plus de v\'erifier le client, il est sage +de v\'erifier que le p\'eriph\'erique de stockage choisi par Bacula est le bon. +Bien que le FileSet soit pr\'esent\'e, il est en fait ignor\'e dans la restauration. +Le processus de restauration choisit ses fichiers en lisant le fichier +{\bf bootstrap}, et restaure tous les fichiers associ\'es au JobId consid\'er\'e +si ce fichier n'est pas sp\'ecifi\'e. + +Enfin, avant de lancer la restauration, notez que le lieu par d\'efaut pour les +fichiers restaur\'es n'est pas leur emplacement d'origine mais le r\'epertoire +{\bf /tmp/bacula-restores}. Vous pouvez modifier cette valeur par d\'efaut dans +le fichier de configuration du Director, ou avec l'option {\bf mod}. Si vous +voulez restaurer les fichiers \`a leurs emplacements d'origine, modifiez l'option +{\bf where} : sp\'ecifiez la racine ({\bf /} ou rien du tout). + +Si vous entrez maintenant {\bf yes}, Bacula lance la restauration. le Storage +Daemon va d'abord requ\'erir le volume {\bf DLT-19Jul02}, puis le {\bf DLT-04Aug02} +une fois qu'il aura extrait les fichiers requis du premier. + +\section{S\'electionner des fichiers par leurs noms} +\index[general]{S\'electionner des fichiers par leurs noms} +\index[general]{Noms de fichiers!S\'electionner des fichiers par leurs} +\addcontentsline{toc}{section}{S\'electionner des fichiers par leurs noms} + +Si vous n'avez qu'un petit nombre de fichiers \`a restaurer dont vous connaissez +les noms, vous pouvez, aux choix, placer ces noms dans un fichier qui sera +lu par Bacula, ou saisir les noms un par un. Les noms de fichier doivent inclure +le chemin absolu. Les caract\`eres jokers ne peuvent \^etre utilis\'es. + +Pour saisir la liste, choisissez l'option 7 dans le menu de la commande {\bf restore} : + +\footnotesize +\begin{verbatim} +To select the JobIds, you have the following choices: + 1: List last 20 Jobs run + 2: List Jobs where a given File is saved + 3: Enter list of comma separated JobIds to select + 4: Enter SQL list command + 5: Select the most recent backup for a client + 6: Select backup for a client before a specified time + 7: Enter a list of files to restore + 8: Enter a list of files to restore before a specified time + 9: Find the JobIds of the most recent backup for a client + 10: Find the JobIds for a backup for a client before a specified time + 11: Enter a list of directories to restore for found JobIds + 12: Cancel +Select item: (1-12): +\end{verbatim} +\normalsize + +Vous \^etes alors invit\'e \`a pr\'eciser le client : + +\footnotesize +\begin{verbatim} +Defined Clients: + 1: Timmy + 2: Tibs + 3: Rufus +Select the Client (1-3): 3 +\end{verbatim} +\normalsize + +Si vous n'avez qu'un client, il est s\'electionn\'e automatiquement. +Finalement, Bacula vous demande d'entrer un nom de fichier : + +\footnotesize +\begin{verbatim} +Enter filename: +\end{verbatim} +\normalsize + +Vous pouvez, \`a ce stade, saisir le chemin absolu et le nom du fichier : + +\footnotesize +\begin{verbatim} +Enter filename: /home/kern/bacula/k/Makefile.in +Enter filename: +\end{verbatim} +\normalsize + +Si Bacula ne peut en trouver aucune copie, il affiche ce qui suit : + +\footnotesize +\begin{verbatim} +Enter filename: junk filename +No database record found for: junk filename +Enter filename: +\end{verbatim} +\normalsize + +Si vous souhaitez que Bacula r\'ecup\`ere la liste des fichiers \`a restaurer depuis +un fichier, r\'edigez ce fichier et donnez lui un nom commen\c{c}ant par le signe +moins (\lt{}) et saisissez-le ici. Lorsque vous avez entr\'e tous les noms de +fichiers, validez une ligne vide. Bacula \'ecrit maintenant le fichier +bootstrap, vous indique les cartouches qui seront utilis\'ees, et vous propose +de valider la restauration : + +\footnotesize +\begin{verbatim} +Enter filename: +Automatically selected Storage: DDS-4 +Bootstrap records written to /home/kern/bacula/working/restore.bsr +The restore job will require the following Volumes: + + test1 +1 file selected to restore. +Run Restore job +JobName: kernsrestore +Bootstrap: /home/kern/bacula/working/restore.bsr +Where: /tmp/bacula-restores +Replace: always +FileSet: Kerns Files +Client: Rufus +Storage: DDS-4 +When: 2003-09-11 10:20:53 +Priority: 10 +OK to run? (yes/mod/no): +\end{verbatim} +\normalsize + +Il est possible d'automatiser la s\'election des fichiers en pla\c{c}ant votre liste +de fichiers dans, part exemple, {\bf /tmp/file-list}, puis en utilisant la +commande suivante : + +\footnotesize +\begin{verbatim} +restore client=Rufus file=----| Stunnel 1 |-----> Port 9102 + |===========| + stunnel-fd2.conf + |===========| + Port 9103 >----| Stunnel 2 |-----> server:29103 + |===========| + Director (server): + stunnel-dir.conf + |===========| + Port 29102 >----| Stunnel 3 |-----> client:29102 + |===========| + stunnel-sd.conf + |===========| + Port 29103 >----| Stunnel 4 |-----> 9103 + |===========| +\end{verbatim} +\normalsize + +\section{Certificates} +\index[general]{Certificates } + +In order for stunnel to function as a server, which it does in our diagram for +Stunnel 1 and Stunnel 4, you must have a certificate and the key. It is +possible to keep the two in separate files, but normally, you keep them in one +single .pem file. You may create this certificate yourself in which case, it +will be self-signed, or you may have it signed by a CA. + +If you want your clients to verify that the server is in fact valid (Stunnel 2 +and Stunnel 3), you will need to have the server certificates signed by a CA +(Certificate Authority), and you will need to have the CA's public certificate +(contains the CA's public key). + +Having a CA signed certificate is {\bf highly} recommended if you are using +your client across the Internet, otherwise you are exposed to the man in the +middle attack and hence loss of your data. + +See below for how to create a self-signed certificate. + +\section{Securing the Data Channel} +\index[general]{Channel!Securing the Data } +\index[general]{Securing the Data Channel } + +To simplify things a bit, let's for the moment consider only the data channel. +That is the connection between the File daemon and the Storage daemon, which +takes place on port 9103. In fact, in a minimalist solution, this is the only +connection that needs to be encrypted, because it is the one that transports your +data. The connection between the Director and the File daemon is simply a +control channel used to start the job and get the job status. + +Normally the File daemon will contact the Storage daemon on port 9103 +(supplied by the Director), so we need an stunnel that listens on port 9103 on +the File daemon's machine, encrypts the data and sends it to the Storage +daemon. This is depicted by Stunnel 2 above. Note that this stunnel is +listening on port 9103 and sending to server:29103. We use port 29103 on the +server because if we would send the data to port 9103, it would go directly to the +Storage daemon, which doesn't understand encrypted data. On the server +machine, we run Stunnel 4, which listens on port 29103, decrypts the data and +sends it to the Storage daemon, which is listening on port 9103. + +\section{Data Channel Configuration} +\index[general]{Modification of bacula-dir.conf for the Data Channel } +\index[general]{baculoa-dir.conf!Modification for the Data Channel } + +The Storage resource of the bacula-dir.conf normally looks something like the +following: + +\footnotesize +\begin{verbatim} +Storage { + Name = File + Address = server + SDPort = 9103 + Password = storage_password + Device = File + Media Type = File +} +\end{verbatim} +\normalsize + +Notice that this is running on the server machine, and it points the File +daemon back to server:9103, which is where our Storage daemon is listening. We +modify this to be: + +\footnotesize +\begin{verbatim} +Storage { + Name = File + Address = localhost + SDPort = 9103 + Password = storage_password + Device = File + Media Type = File +} +\end{verbatim} +\normalsize + +This causes the File daemon to send the data to the stunnel running on +localhost (the client machine). We could have used client as the address as +well. + +\section{Stunnel Configuration for the Data Channel} +\index[general]{Stunnel Configuration for the Data Channel } + +In the diagram above, we see above Stunnel 2 that we use stunnel-fd2.conf on the +client. A pretty much minimal config file would look like the following: + +\footnotesize +\begin{verbatim} +client = yes +[29103] +accept = localhost:9103 +connect = server:29103 +\end{verbatim} +\normalsize + +The above config file does encrypt the data but it does not require a +certificate, so it is subject to the man in the middle attack. The file I +actually used, stunnel-fd2.conf, looked like this: + +\footnotesize +\begin{verbatim} +# +# Stunnel conf for Bacula client -> SD +# +pid = /home/kern/bacula/bin/working/stunnel.pid +# +# A cert is not mandatory here. If verify=2, a +# cert signed by a CA must be specified, and +# either CAfile or CApath must point to the CA's +# cert +# +cert = /home/kern/stunnel/stunnel.pem +CAfile = /home/kern/ssl/cacert.pem +verify = 2 +client = yes +# debug = 7 +# foreground = yes +[29103] +accept = localhost:9103 +connect = server:29103 +\end{verbatim} +\normalsize + +You will notice that I specified a pid file location because I ran stunnel +under my own userid so I could not use the default, which requires root +permission. I also specified a certificate that I have as well as verify level +2 so that the certificate is required and verified, and I must supply the +location of the CA (Certificate Authority) certificate so that the stunnel +certificate can be verified. Finally, you will see that there are two lines +commented out, which when enabled, produce a lot of nice debug info in the +command window. + +If you do not have a signed certificate (stunnel.pem), you need to delete the +cert, CAfile, and verify lines. + +Note that the stunnel.pem, is actually a private key and a certificate in a +single file. These two can be kept and specified individually, but keeping +them in one file is more convenient. + +The config file, stunnel-sd.conf, needed for Stunnel 4 on the server machine +is: + +\footnotesize +\begin{verbatim} +# +# Bacula stunnel conf for Storage daemon +# +pid = /home/kern/bacula/bin/working/stunnel.pid +# +# A cert is mandatory here, it may be self signed +# If it is self signed, the client may not use +# verify +# +cert = /home/kern/stunnel/stunnel.pem +client = no +# debug = 7 +# foreground = yes +[29103] +accept = 29103 +connect = 9103 +\end{verbatim} +\normalsize + +\section{Starting and Testing the Data Encryption} +\index[general]{Starting and Testing the Data Encryption } +\index[general]{Encryption!Starting and Testing the Data } + +It will most likely be the simplest to implement the Data Channel encryption +in the following order: + +\begin{itemize} +\item Setup and run Bacula backing up some data on your client machine + without encryption. +\item Stop Bacula. +\item Modify the Storage resource in the Director's conf file. +\item Start Bacula +\item Start stunnel on the server with: + + \footnotesize +\begin{verbatim} + stunnel stunnel-sd.conf + +\end{verbatim} +\normalsize + +\item Start stunnel on the client with: + + \footnotesize +\begin{verbatim} + stunnel stunnel-fd2.conf + +\end{verbatim} +\normalsize + +\item Run a job. +\item If it doesn't work, turn debug on in both stunnel conf files, restart + the stunnels, rerun the job, repeat until it works. + \end{itemize} + +\section{Encrypting the Control Channel} +\index[general]{Channel!Encrypting the Control } +\index[general]{Encrypting the Control Channel } + +The Job control channel is between the Director and the File daemon, and as +mentioned above, it is not really necessary to encrypt, but it is good +practice to encrypt it as well. The two stunnels that are used in this case +will be Stunnel 1 and Stunnel 3 in the diagram above. Stunnel 3 on the server +might normally listen on port 9102, but if you have a local File daemon, this +will not work, so we make it listen on port 29102. It then sends the data to +client:29102. Again we use port 29102 so that the stunnel on the client +machine can decrypt the data before passing it on to port 9102 where the File +daemon is listening. + +\section{Control Channel Configuration} +\index[general]{Control Channel Configuration } + +We need to modify the standard Client resource, which would normally look +something like: + +\footnotesize +\begin{verbatim} +Client { + Name = client-fd + Address = client + FDPort = 9102 + Catalog = BackupDB + Password = "xxx" +} +\end{verbatim} +\normalsize + +to be: + +\footnotesize +\begin{verbatim} +Client { + Name = client-fd + Address = localhost + FDPort = 29102 + Catalog = BackupDB + Password = "xxx" +} +\end{verbatim} +\normalsize + +This will cause the Director to send the control information to +localhost:29102 instead of directly to the client. + +\section{Stunnel Configuration for the Control Channel} +\index[general]{Config Files for stunnel to Encrypt the Control Channel } + +The stunnel config file, stunnel-dir.conf, for the Director's machine would +look like the following: + +\footnotesize +\begin{verbatim} +# +# Bacula stunnel conf for the Directory to contact a client +# +pid = /home/kern/bacula/bin/working/stunnel.pid +# +# A cert is not mandatory here. If verify=2, a +# cert signed by a CA must be specified, and +# either CAfile or CApath must point to the CA's +# cert +# +cert = /home/kern/stunnel/stunnel.pem +CAfile = /home/kern/ssl/cacert.pem +verify = 2 +client = yes +# debug = 7 +# foreground = yes +[29102] +accept = localhost:29102 +connect = client:29102 +\end{verbatim} +\normalsize + +and the config file, stunnel-fd1.conf, needed to run stunnel on the Client +would be: + +\footnotesize +\begin{verbatim} +# +# Bacula stunnel conf for the Directory to contact a client +# +pid = /home/kern/bacula/bin/working/stunnel.pid +# +# A cert is not mandatory here. If verify=2, a +# cert signed by a CA must be specified, and +# either CAfile or CApath must point to the CA's +# cert +# +cert = /home/kern/stunnel/stunnel.pem +CAfile = /home/kern/ssl/cacert.pem +verify = 2 +client = yes +# debug = 7 +# foreground = yes +[29102] +accept = localhost:29102 +connect = client:29102 +\end{verbatim} +\normalsize + +\section{Starting and Testing the Control Channel} +\index[general]{Starting and Testing the Control Channel } +\index[general]{Channel!Starting and Testing the Control } + +It will most likely be the simplest to implement the Control Channel +encryption in the following order: + +\begin{itemize} +\item Stop Bacula. +\item Modify the Client resource in the Director's conf file. +\item Start Bacula +\item Start stunnel on the server with: + + \footnotesize +\begin{verbatim} + stunnel stunnel-dir.conf + +\end{verbatim} +\normalsize + +\item Start stunnel on the client with: + + \footnotesize +\begin{verbatim} + stunnel stunnel-fd1.conf + +\end{verbatim} +\normalsize + +\item Run a job. +\item If it doesn't work, turn debug on in both stunnel conf files, restart + the stunnels, rerun the job, repeat until it works. + \end{itemize} + +\section{Using stunnel to Encrypt to a Second Client} +\index[general]{Using stunnel to Encrypt to a Second Client } +\index[general]{Client!Using stunnel to Encrypt to a Second } + +On the client machine, you can just duplicate the setup that you have on the +first client file for file and it should work fine. + +In the bacula-dir.conf file, you will want to create a second client pretty +much identical to how you did for the first one, but the port number must be +unique. We previously used: + +\footnotesize +\begin{verbatim} +Client { + Name = client-fd + Address = localhost + FDPort = 29102 + Catalog = BackupDB + Password = "xxx" +} +\end{verbatim} +\normalsize + +so for the second client, we will, of course, have a different name, and we +will also need a different port. Remember that we used port 29103 for the +Storage daemon, so for the second client, we can use port 29104, and the +Client resource would look like: + +\footnotesize +\begin{verbatim} +Client { + Name = client2-fd + Address = localhost + FDPort = 29104 + Catalog = BackupDB + Password = "yyy" +} +\end{verbatim} +\normalsize + +Now, fortunately, we do not need a third stunnel to on the Director's machine, +we can just add the new port to the config file, stunnel-dir.conf, to make: + +\footnotesize +\begin{verbatim} +# +# Bacula stunnel conf for the Directory to contact a client +# +pid = /home/kern/bacula/bin/working/stunnel.pid +# +# A cert is not mandatory here. If verify=2, a +# cert signed by a CA must be specified, and +# either CAfile or CApath must point to the CA's +# cert +# +cert = /home/kern/stunnel/stunnel.pem +CAfile = /home/kern/ssl/cacert.pem +verify = 2 +client = yes +# debug = 7 +# foreground = yes +[29102] +accept = localhost:29102 +connect = client:29102 +[29104] +accept = localhost:29102 +connect = client2:29102 +\end{verbatim} +\normalsize + +There are no changes necessary to the Storage daemon or the other stunnel so +that this new client can talk to our Storage daemon. + +\section{Creating a Self-signed Certificate} +\index[general]{Creating a Self-signed Certificate } +\index[general]{Certificate!Creating a Self-signed } + +You may create a self-signed certificate for use with stunnel that will permit +you to make it function, but will not allow certificate validation. The .pem +file containing both the certificate and the key can be made with the +following, which I put in a file named {\bf makepem}: + +\footnotesize +\begin{verbatim} +#!/bin/sh +# +# Simple shell script to make a .pem file that can be used +# with stunnel and Bacula +# +OPENSSL=openssl + umask 77 + PEM1="/bin/mktemp openssl.XXXXXX" + PEM2="/bin/mktemp openssl.XXXXXX" + ${OPENSSL} req -newkey rsa:1024 -keyout $PEM1 -nodes \ + -x509 -days 365 -out $PEM2 + cat $PEM1 > stunnel.pem + echo "" >>stunnel.pem + cat $PEM2 >>stunnel.pem + rm $PEM1 $PEM2 +\end{verbatim} +\normalsize + +The above script will ask you a number of questions. You may simply answer +each of them by entering a return, or if you wish you may enter your own data. + + +\section{Getting a CA Signed Certificate} +\index[general]{Certificate!Getting a CA Signed } +\index[general]{Getting a CA Signed Certificate } + +The process of getting a certificate that is signed by a CA is quite a bit +more complicated. You can purchase one from quite a number of PKI vendors, but +that is not at all necessary for use with Bacula. + +To get a CA signed +certificate, you will either need to find a friend that has setup his own CA +or to become a CA yourself, and thus you can sign all your own certificates. +The book OpenSSL by John Viega, Matt Mesier \& Pravir Chandra from O'Reilly +explains how to do it, or you can read the documentation provided in the +Open-source PKI Book project at Source Forge: +\elink{ +http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm} +{http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}. +Note, this link may change. + +\section{Using ssh to Secure the Communications} +\index[general]{Communications!Using ssh to Secure the } +\index[general]{Using ssh to Secure the Communications } + +Please see the script {\bf ssh-tunnel.sh} in the {\bf examples} directory. It +was contributed by Stephan Holl. diff --git a/docs/manuals/fr/concepts/supportedchangers.tex b/docs/manuals/fr/concepts/supportedchangers.tex new file mode 100644 index 00000000..ed020497 --- /dev/null +++ b/docs/manuals/fr/concepts/supportedchangers.tex @@ -0,0 +1,66 @@ +%% +%% + +\chapter{Librairies support\'ees} +\label{_ChapterStart21} +\addcontentsline{toc}{section}{Librairies support\'ees} + +\section{Mod\`eles de librairies support\'es} +\label{Models} +\index[general]{Mod\`eles de librairies support\'ees} +\index[general]{Librairies!Support\'ees} +\addcontentsline{toc}{section}{Mod\`eles de librairies support\'es} + +J'h\'esite \`a qualifier ces librairies de "support\'ees", car les seules +en ma possession et que je peux tester sont une HP SureStore DAT40X6 et +une Overland PowerLoader LTO-2. Toutes les autres librairies cit\'ees ici +ont \'et\'e raport\'ees comme fonctionnant avec Bacula par des utilisateurs. +Notez que dans la colonne Capacit\'e/Slot, je pr\'ecise la capacit\'e compress\'ee +par cartouche (ou slot). + +\addcontentsline{lot}{table}{Librairies connues pour fonctionner avec Bacula} +\begin{longtable}{|p{0.6in}|p{0.8in}|p{1.9in}|p{0.8in}|p{0.5in}|p{0.75in}|} + \hline +\multicolumn{1}{|c| }{\bf OS } & \multicolumn{1}{c| }{\bf Fabr. } & +\multicolumn{1}{c| }{\bf Media } & \multicolumn{1}{c| }{\bf Mod\`ele } & +\multicolumn{1}{c| }{\bf Slots } & \multicolumn{1}{c| }{\bf Cap/Slot } \\ + \hline {Linux } & {Adic } & {DDS-3} & {Adic 1200G } & {12} & {-} \\ + \hline {Linux } & {Adic } & {DLT} & {FastStore 4000 } & {7} & {20GB} \\ + \hline {Linux } & {Adic } & {LTO-1/2, SDLT 320 } & {Adic Scalar 24 } & {24} & {100GB } \\ + \hline {Linux } & {Adic } & {LTO-2 } & {Adic FastStor 2, Sun Storedge L8 } & {8} & {200GB } \\ + \hline {- } & {CA-VM } & {?? } & {Tape } & {??} & {?? } \\ + \hline {Linux} & {Dell} & {DLT VI,LTO-2} & {PowerVault 122T/132T/136T } & {-} & {100GB } \\ + \hline {Linux } & {Dell} & {LTO-2} & {PowerVault 124T } & {-} & {200GB } \\ + \hline {- } & {DFSMS } & {?? } & {VM RMM} & {-} & {?? } \\ + \hline {Linux } & {Exabyte } & {VXA2 } & {VXA PacketLoader 1x10 2U } & {10} & {80/160GB } \\ + \hline {- } & {Exabyte } & {LTO } & {Magnum 1x7 LTO Tape Auotloader } & {7} & {200/400GB } \\ + \hline {Linux Gentoo 1.4 } & {Exabyte } & {AIT-2 } & {215A } & {15 (2 drives)} & {50GB } \\ + \hline {Linux } & {HP } & {DDS-4 } & {SureStore DAT-40X6 } & {6 } & {40GB } \\ + \hline {Linux } & {HP } & {Ultrium-2/LTO } & {MSL 6000/ 60030/ 5052 } & {28 } & {200/400GB } \\ + \hline {- } & {HP } & {DLT } & {A4853 DLT } & {30} & {40/70GB } \\ + \hline {Linux } & {HP (Compaq) } & {DLT VI } & {Compaq TL-895 } & {96+4 import export} & {35/70GB } \\ + \hline {z/VM } & {IBM } & {?? } & {IBM Tape Manager } & {-} & {?? } \\ + \hline {z/VM } & {IBM } & {?? } & {native tape } & {-} & {?? } \\ + \hline {Linux } & {IBM } & {LTO } & {IBM 3581 Ultrium Tape Loader } & {7} & {200/400GB } \\ + \hline {SuSE 9.0 } & {IBM } & {LTO } & {IBM 3581 Ultrium Tape Loader } & {7} & {200/400GB } \\ + \hline {FreeBSD 5.4} & {IBM } & {DLT} & {IBM 3502-R14 -- rebranded ATL L-500} & {14} & {35/70GB } \\ + \hline {Debian} & {Overland } & {LTO } & {Overland LoaderXpress LTO/DLT8000 } & {10-19} & {40-100GB } \\ + \hline {Fedora} & {Overland } & {LTO } & {Overland PowerLoader LTO-2 } & {10-19} & {200/400GB } \\ + \hline {FreeBSD 5.4-Stable} & {Overland} & {LTO-2} & {Overland Powerloader tape} & {17} & {100GB } \\ + \hline {- } & {Overland} & {LTO } & {Overland Neo2000 LTO } & {26-30} & {100GB } \\ + \hline {- } & {Quantum } & {?? } & {Super Loader } & {??} & {?? } \\ + \hline {FreeBSD 4.9 } & {QUALSTAR TLS-4210 (Qualstar) } & {AIT1: 36GB, AIT2: 50GB all +uncomp } & {QUALSTAR TLS-4210 } & {12} & {AIT1: 36GB, AIT2: 50GB all uncomp }\\ + \hline {Linux } & {Skydata } & {DLT } & {ATL-L200 } & {8} & {40/80 } \\ + \hline {- } & {Sony } & {DDS-4 } & {TSL-11000 } & {8} & {40GB } \\ + \hline {Linux } & {Sony } & {AIT-2} & {LIB-304(SDX-500C) } & {?} & {200GB } \\ + \hline {Linux } & {Sony } & {AIT-3} & {LIB-D81) } & {?} & {200GB } \\ + \hline {FreeBSD 4.9-STABLE } & {Sony } & {AIT-1 } & {TSL-SA300C } & {4} & {45/70GB }\\ + \hline {- } & {Storagetek } & {DLT } & {Timberwolf DLT } & {6} & {40/70 } \\ + \hline {- } & {Storagetek } & {?? } & {ACSLS } & {??} & {?? } \\ + \hline {Solaris } & {Sun } & {4mm DLT } & {Sun Desktop Archive Python 29279 } & {4} & {20GB } \\ + \hline {Linux } & {Tandberg } & {DLT VI } & {VS 640 } & {8?} & {35/70GB } \\ + \hline {Linux 2.6.x } & {Tandberg Data } & {SLR100 } & {SLR100 Autoloader } & {8} & {50/100GB }\\ +\hline + +\end{longtable} diff --git a/docs/manuals/fr/concepts/supporteddrives.tex b/docs/manuals/fr/concepts/supporteddrives.tex new file mode 100644 index 00000000..d5b587a0 --- /dev/null +++ b/docs/manuals/fr/concepts/supporteddrives.tex @@ -0,0 +1,174 @@ +%% +%% + +\chapter{Lecteurs de bandes support\'es} +\label{_ChapterStart19} +\index[general]{Lecteurs de bandes support\'es } +\index[general]{Lecteurs!bandes support\'ees } +\addcontentsline{toc}{section}{Lecteurs de bandes support\'es} + +M\^eme si votre lecteur est dans la liste ci dessous, v\'erifiez le +\ilink{Chapitre Test des Lecteurs Bandes}{btape1} de ce manuel +pour les proc\'edures que vous pouvez utiliser pour v\'erifier si votre +lecteur de bandes est susceptible de fonctionner avec Bacula. +Si votre lecteur est en mode bloc +fixe, il peut para\^itre fonctionner avec Bacula jusqu'\`a ce que vous essayiez de +restaurer et que Bacula tente de se positionner sur la bande. Seuls la +proc\'edure ci-dessus et vos propres tests peuvent vous garantir un +fonctionnement correct. + +Il est tr\`es difficile de fournir une liste de lecteurs de bandes +support\'es, ou de lecteurs qui sont connus pour fonctionner avec Bacula en +raison du peu de retours de la part des usagers. (par cons\'equent, si vous +utilisez Bacula sur un lecteur qui ne figure pas dans la liste, merci de nous +le faire savoir). Selon les informations provenant de nos utilisateurs, les +lecteurs suivants sont connus pour fonctionner avec Bacula. Un trait d'union +dans une colonne signifie "inconnu" : + +\begin{longtable}{|l|l|l|l|l|} + \hline +\multicolumn{1}{|c| }{\bf OS } & \multicolumn{1}{c| }{\bf Fabr. } & +\multicolumn{1}{c| }{\bf Media } & \multicolumn{1}{c| }{\bf Mod\`ele } & +\multicolumn{1}{c| }{\bf Capacit\'e } \\ + \hline +{- } & {ADIC } & {DLT } & {Adic Scalar 100 DLT } & {100GB } \\ + \hline +{- } & {ADIC } & {DLT } & {Adic Fastor 22 DLT } & {- } \\ + \hline +{- } & {- } & {DDS } & {Compaq DDS 2,3,4 } & {- } \\ + \hline +{- } & {Exabyte } & {- } & {Lecteurs Exabyte de moins de dix ans } & {- +} \\ + \hline +{- } & {Exabyte } & {- } & {Exabyte VXA drives } & {- } \\ + \hline +{- } & {HP } & {Travan 4 } & {Colorado T4000S } & {- } \\ + \hline +{- } & {HP } & {DLT } & {HP DLT drives } & {- } \\ + \hline +{- } & {HP } & {LTO } & {HP LTO Ultrium drives } & {- } \\ + \hline +{FreeBSD 4.10 RELEASE } & {HP } & {DAT } & {HP StorageWorks DAT72i } & {- +} \\ + \hline +{- } & {Overland } & {LTO } & {LoaderXpress LTO } & {- } \\ + \hline +{- } & {Overland } & {- } & {Neo2000 } & {- } \\ + \hline +{- } & {OnStream } & {- } & {OnStream drives (see below) } & {- } \\ + \hline +{- } & {Quantum } & {DLT } & {DLT-8000 } & {40/80GB } \\ + \hline +{Linux } & {Seagate } & {DDS-4 } & {Scorpio 40 } & {20/40GB } \\ + \hline +{FreeBSD 4.9 STABLE } & {Seagate } & {DDS-4 } & {STA2401LW } & {20/40GB } +\\ + \hline +{FreeBSD 5.2.1 pthreads patched RELEASE } & {Seagate } & {AIT-1 } & +{STA1701W } & {35/70GB } \\ + \hline +{Linux } & {Sony } & {DDS-2,3,4 } & {- } & {4-40GB } \\ + \hline +{Linux } & {Tandberg } & {- } & {Tandbert MLR3 } & {- } \\ + \hline +{FreeBSD } & {Tandberg } & {- } & {Tandberg SLR6 } & {- } \\ + \hline +{Solaris } & {Tandberg } & {- } & {Tandberg SLR75 } & {- } \\ + \hline +{Linux Gentoo } & {ADIC } & {- } & {IBM Ultrium LTO I } & {100/200 Go } +\\ \hline + +\end{longtable} + +Une liste des +\ilink{Librarires support\'ees}{Models} figure dans le +\ilink{chapitre librairies (autochangers)}{_ChapterStart} de +ce document, o\`u vous trouverez d'autres lecteurs de bandes qui fonctionnent avec +Bacula. + +\section{Lecteurs de bande non support\'es} +\label{UnSupportedDrives} +\index[general]{Lecteurs de bande non support\'es } +\addcontentsline{toc}{section}{Lecteurs de bande non support\'es} + +Auparavant les lecteurs de bandes OnStream IDE-SCSI ne fonctionnaient pas avec +Bacula. A partir de la version 1.33 de Bacula et de la version 0.9.14 du +pilote noyau ou sup\'erieur,ce lecteur est support\'e. Consultez le chapitre +de test car vous devez le configurer pour fonctionner en mode blocs de taille +fixe. + +Les lecteurs QIC sont connus pour avoir nombre de particularit\'es (taille de +blocs fixe, et un EOF plut\^ot que deux pour terminer la bande). En +cons\'equence, vous devrez \^etre particuli\`erement attentif \`a sa +configuration pour le faire fonctionner avec Bacula. + +\section{A l'attention des utilisateurs de FreeBSD !!!} +\index[general]{L'attention des utilisateurs de FreeBSD } +\index[general]{FreeBSD!l'attention des utilisateurs de } +\addcontentsline{toc}{section}{l'attention des utilisateurs de FreeBSD !!!} + +A moins que vous n'ayez appliqu\'e un correctif sur la biblioth\`eque pthreads +de votre syst\`eme FreeBSD, vous perdrez des donn\'ees quand Bacula aura +rempli une bande et passera \`a la suivante. La raison en est que les +biblioth\`eques pthreads sans correctifs \'echouent \`a retourner un \'etat +d'alerte \`a Bacula signalant que la fin de bande est proche. Consultez le +\ilink{chapitre test des lecteurs de bandes}{FreeBSDTapes} de +ce manuel pour d'importantes informations concernant la configuration de votre +lecteur de bande pour qu'il soit compatible avec {\bf Bacula}. + +\section{Librairiess support\'ees} +\index[general]{Librairiess support\'ees } +\addcontentsline{toc}{section}{Librairies support\'ees} + +Pour des informations sur les libraries (autochangeurs) support\'ees, allez +voir la section +\ilink{Libraries connues pour fonctionner avec Bacula}{Models} du chapitre +Librairies support\'ees de ce manuel. + +\section{Sp\'ecifications des cartouches} +\index[general]{Sp\'ecifications!Cartouches} +\index[general]{Cartouches Sp\'ecifications} +\addcontentsline{toc}{section}{Sp\'ecifications des cartouches} +Nous ne pouvons vraiment pas vous dire quel lecteur acheter pour utiliser Bacula. +Cependant, nous pouvons recommander d'\'eviter les lecteurs DDS. La +technologie est plut\^ot ancienne et ces lecteurs n\'ecessitent de fr\'equents +nettoyages. Les lecteurs DLT sont g\'en\'eralement bien meilleurs (technologie +plus r\'ecente) et ne requi\`erent pas autant d'op\'erations de nettoyage. + +Ci-dessous, vous trouverez une table de sp\'ecifications de cartouches DLT et LTO +qui vous permettra de vous faire une id\'ee de la capacit\'e et de la rapidit\'e des +lecteurs et cartouches modernes. Les capacit\'es report\'ees ici sont les natives, +sans compression. Tous les lecteurs modernes pratiquent la compression +mat\'erielle, et les fabricants affichent souvent une capacit\'e compress\'ee avec un +ratio de 2:1. Le facteur de compression r\'eel d\'epend principalement des donn\'ees +sauvegard\'ees, mais je pense qu'un ratio 1,5:1 est beaucoup plus raisonnable +(autrement dit, multipliez la valeur de la table par 1,5 pour obtenir une +estimation grossi\`ere de la capacit\'e compress\'ee). Les taux de transfert sont +arrondis au GB/hr le plus proche. Les valeurs sont fournies par les divers +fabricants. + +Le type de media est la d\'esignation du fabricant, vous n'\^etes pas oblig\'e de +l'utiliser (mais vous devriez...) dans vos ressources de configuration Bacula. + + +\begin{tabular}{|c|c|c|c} +Type de media & Type de lecteur & Capacit\'e des media & Taux de transfert \\ \hline +DDS-1 & DAT & 2 GB & ?? GB/hr \\ \hline +DDS-2 & DAT & 4 GB & ?? GB/hr \\ \hline +DDS-3 & DAT & 12 GB & 5.4 GB/hr \\ \hline +Travan 40 & Travan & 20 GB & ?? GB/hr \\ \hline +DDS-4 & DAT & 20 GB & 11 GB/hr \\ \hline +VXA-1 & Exabyte & 33 GB & 11 GB/hr \\ \hline +DAT-72 & DAT & 36 GB & 13 GB/hr \\ \hline +DLT IV & DLT8000 & 40 GB & 22 GB/hr \\ \hline +VXA-2 & Exabyte & 80 GB & 22 GB/hr \\ \hline +Half-high Ultrum 1 & LTO 1 & 100 GB & 27 GB/hr \\ \hline +Ultrium 1 & LTO 1 & 100 GB & 54 GB/hr \\ \hline +Super DLT 1 & SDLT 220 & 110 GB & 40 GB/hr \\ \hline +VXA-3 & Exabyte & 160 GB & 43 GB/hr \\ \hline +Super DLT I & SDLT 320 & 160 GB & 58 GB/hr \\ \hline +Ultrium 2 & LTO 2 & 200 GB & 108 GB/hr \\ \hline +Super DLT II & SDLT 600 & 300 GB & 127 GB/hr \\ \hline +VXA-4 & Exabyte & 320 GB & 86 GB/hr \\ \hline +Ultrium 3 & LTO 3 & 400 GB & 216 GB/hr \\ \hline +\end{tabular} diff --git a/docs/manuals/fr/concepts/supportedoses.tex b/docs/manuals/fr/concepts/supportedoses.tex new file mode 100644 index 00000000..e5354c1d --- /dev/null +++ b/docs/manuals/fr/concepts/supportedoses.tex @@ -0,0 +1,46 @@ +%% +%% + +\chapter{Syst\`emes d'exploitation support\'es} +\label{SupportedOSes} +\index[general]{Syst\`emes d'exploitation support\'es } + +\begin{itemize} +\item Syst\`emes Linux (compil\'e et test\'e sur RedHat Enterprise Linux + 3.0). +\item Si vous avez un syst\`eme Red Hat r\'ecent ex\'ecutant le noyau 2.4.x + et si vous avez le r\'epertoire {\bf /lib/tls} install\'e sur votre + syst\`eme (par d\'efaut normalement), {\bf Bacula ne fonctionnera pas + correctement} Ceci est d\^u \`a la nouvelle biblioth\`eque pthreads qui est + d\'efectueuse. Vous devez supprimer ce r\'epertoire avant d'ex\'ecuter + Bacula, ou vous pouvez simplement le renommer en {\bf /lib/tls-broken} puis + red\'emarrer votre machine (une des rares occasions o\`u; Linux doit \^etre + red\'emarr\'e). Si vous ne souhaitez pas d\'eplacer/renommer /lib/tls, une + autre alternative est de placer la variable d'environnement + ``LD\_ASSUME\_KERNEL=2.4.19'' avant d'ex\'ecuter Bacula. Pour cette option, + vous n'avez pas besoin de red\'emarrer, et tous les programmes autres que + {\bf Bacula} continueront d'utiliser {\bf /lib/tls}. + + Le probl\`eme n'existe pas sur les noyaux 2.6. + +\item La plupart des distributions Linux les plus courantes (Gentoo, SuSE, Mandriva, Debian, + ...). +\item Diff\'erentes versions de Solaris. +\item FreeBSD (pilote de bande support\'e \`a partir de la version 1.30 -- + allez voir les consid\'erations {\bf importantes} dans la section + \ilink{Configuration des lecteurs de bandes sur FreeBSD}{FreeBSDTapes} + du chapitre Test des Bandes de ce manuel.) +\item Windows (Win98/Me, WinNT/2K/XP) clients binaires ({\bf File Daemon}). +\item MacOS X/Darwin (voir + \elink{ http://fink.sourceforge.net/}{http://fink.sourceforge.net/} pour + obtenir les paquets) +\item OpenBSD Client ({\bf File Daemon}). +\item Irix Client ({\bf File Daemon}). +\item Tru64 +\item {\bf Bacula} est r\'eput\'e fonctionner sur d'autres syst\`emes (AIX, + BSDI, HPUX, ...) mais nous ne les avons pas test\'e personnellement. +\item RHat 7.2 AS2, AS3, AS4, Fedora Core 2, SuSE SLES 7,8,9, Debian Woody et Sarge Linux sur + S/390 et Linux sur zSeries. +\item Voir le chapitre de Portage de la Documentation Pour Developpeurs pour + les informations concernant le portage sur d'autres syst\`emes. +\end{itemize} diff --git a/docs/manuals/fr/concepts/thanks.tex b/docs/manuals/fr/concepts/thanks.tex new file mode 100644 index 00000000..aa324925 --- /dev/null +++ b/docs/manuals/fr/concepts/thanks.tex @@ -0,0 +1,102 @@ +%% +%% + +\chapter{Thanks} +\label{ThanksChapter} +\index[general]{Thanks } +I thank everyone who has helped this project. Unfortunately, I cannot +thank everyone (bad memory). However, the AUTHORS file in the main source +code directory should include the names of all persons who have contributed +to the Bacula project. Just the same, I would like to include thanks below +to special contributors as well as to the major contributors to the current +release. + +Thanks to Richard Stallman for starting the Free Software movement and for +bringing us gcc and all the other GNU tools as well as the GPL license. + +Thanks to Linus Torvalds for bringing us Linux. + +Thanks to all the Free Software programmers. Without being able to peek at +your code, and in some cases, take parts of it, this project would have been +much more difficult. + +Thanks to John Walker for suggesting this project, giving it a name, +contributing software he has written, and for his programming efforts on +Bacula as well as having acted as a constant sounding board and source of +ideas. + +Thanks to the apcupsd project where I started my Free Software efforts, and +from which I was able to borrow some ideas and code that I had written. + +Special thanks to D. Scott Barninger for writing the bacula RPM spec file, +building all the RPM files and loading them onto Source Forge. This has been a +tremendous help. + +Many thanks to Karl Cunningham for converting the manual from html format to +LaTeX. It was a major effort flawlessly done that will benefit the Bacula +users for many years to come. Thanks Karl. + +Thanks to Dan Langille for the {\bf incredible} amount of testing he did on +FreeBSD. His perseverance is truly remarkable. Thanks also for the many +contributions he has made to improve Bacula (pthreads patch for FreeBSD, +improved start/stop script and addition of Bacula userid and group, stunnel, +...), his continuing support of Bacula users. He also wrote the PostgreSQL +driver for Bacula and has been a big help in correcting the SQL. + +Thanks to multiple other Bacula Packagers who make and release packages for +different platforms for Bacula. + +Thanks to Christopher Hull for developing the native Win32 Bacula emulation +code and for contributing it to the Bacula project. + +Thanks to Robert Nelson for bringing our Win32 implementation up to par +with all the same features that exist in the Unix/Linux versions. In +addition, he has ported the Director and Storage daemon to Win32! + +Thanks to Thorsten Engel for his excellent knowledge of Win32 systems, and +for making the Win32 File daemon Unicode compatible, as well as making +the Win32 File daemon interface to Microsoft's Volume Shadow Copy (VSS). +These two are big pluses for Bacula! + +Thanks to Landon Fuller for writing both the communications and the +data encryption code for Bacula. + +Thanks to Arno Lehmann for his excellent and infatigable help and advice +to users. + +Thanks to all the Bacula users, especially those of you who have contributed +ideas, bug reports, patches, and new features. + +Bacula can be enabled with data encryption and/or communications +encryption. If this is the case, you will be including OpenSSL code that +that contains cryptographic software written by Eric Young +(eay@cryptsoft.com) and also software written by Tim Hudson +(tjh@cryptsoft.com). + +The Bat (Bacula Administration Tool) graphs are based in part on the work +of the Qwt project (http://qwt.sf.net). + +The original variable expansion code used in the LabelFormat comes from the +Open Source Software Project (www.ossp.org). It has been adapted and extended +for use in Bacula. This code is now deprecated. + +There have been numerous people over the years who have contributed ideas, +code, and help to the Bacula project. The file AUTHORS in the main source +release file contains a list of contributors. For all those who I have +left out, please send me a reminder, and in any case, thanks for your +contribution. + +Thanks to the Free Software Foundation Europe e.V. for assuming the +responsibilities of protecting the Bacula copyright. + +% TODO: remove this from the book? +\section*{Copyrights and Trademarks} +\index[general]{Trademarks!Copyrights and } +\index[general]{Copyrights and Trademarks } + +Certain words and/or products are Copyrighted or Trademarked such as Windows +(by Microsoft). Since they are numerous, and we are not necessarily aware of +the details of each, we don't try to list them here. However, we acknowledge +all such Copyrights and Trademarks, and if any copyright or trademark holder +wishes a specific acknowledgment, notify us, and we will be happy to add it +where appropriate. diff --git a/docs/manuals/fr/concepts/tls.tex b/docs/manuals/fr/concepts/tls.tex new file mode 100644 index 00000000..6c90e110 --- /dev/null +++ b/docs/manuals/fr/concepts/tls.tex @@ -0,0 +1,315 @@ + +\chapter{Bacula TLS -- Communications Encryption} +\label{CommEncryption} +\index[general]{TLS -- Communications Encryption} +\index[general]{Communications Encryption} +\index[general]{Encryption!Communications} +\index[general]{Encryption!Transport} +\index[general]{Transport Encryption} +\index[general]{TLS} + +Bacula TLS (Transport Layer Security) is built-in network +encryption code to provide secure network transport similar to +that offered by {\bf stunnel} or {\bf ssh}. The data written to +Volumes by the Storage daemon is not encrypted by this code. +For data encryption, please see the \ilink{Data Encryption +Chapter}{DataEncryption} of this manual. + +The Bacula encryption implementations were written by Landon Fuller. + +Supported features of this code include: +\begin{itemize} +\item Client/Server TLS Requirement Negotiation +\item TLSv1 Connections with Server and Client Certificate +Validation +\item Forward Secrecy Support via Diffie-Hellman Ephemeral Keying +\end{itemize} + +This document will refer to both "server" and "client" contexts. These +terms refer to the accepting and initiating peer, respectively. + +Diffie-Hellman anonymous ciphers are not supported by this code. The +use of DH anonymous ciphers increases the code complexity and places +explicit trust upon the two-way CRAM-MD5 implementation. CRAM-MD5 is +subject to known plaintext attacks, and it should be considered +considerably less secure than PKI certificate-based authentication. + +Appropriate autoconf macros have been added to detect and use OpenSSL +if enabled on the {\bf ./configure} line with {\bf \verb?--?with-openssl} + +\section{TLS Configuration Directives} +Additional configuration directives have been added to all the daemons +(Director, File daemon, and Storage daemon) as well as the various +different Console programs. +These new directives are defined as follows: + +\begin{description} +\item [TLS Enable = \lt{}yes|no\gt{}] +Enable TLS support. If TLS is not enabled, none of the other TLS directives +have any effect. In other words, even if you set {\bf TLS Require = yes} +you need to have TLS enabled or TLS will not be used. + +\item [TLS Require = \lt{}yes|no\gt{}] +Require TLS connections. This directive is ignored unless {\bf TLS Enable} +is set to {\bf yes}. If TLS is not required, and TLS is enabled, then +Bacula will connect with other daemons either with or without TLS depending +on what the other daemon requests. If TLS is enabled and TLS is required, +then Bacula will refuse any connection that does not use TLS. + +\item [TLS Certificate = \lt{}Filename\gt{}] +The full path and filename of a PEM encoded TLS certificate. It can be +used as either a client or server certificate. PEM stands for Privacy +Enhanced Mail, but in this context refers to how the certificates are +encoded. It is used because PEM files are base64 encoded and hence ASCII +text based rather than binary. They may also contain encrypted +information. + +\item [TLS Key = \lt{}Filename\gt{}] +The full path and filename of a PEM encoded TLS private key. It must +correspond to the TLS certificate. + +\item [TLS Verify Peer = \lt{}yes|no\gt{}] +Verify peer certificate. Instructs server to request and verify the +client's x509 certificate. Any client certificate signed by a known-CA +will be accepted unless the TLS Allowed CN configuration directive is used, +in which case the client certificate must correspond to the Allowed +Common Name specified. This directive is valid only for a server +and not in a client context. + +\item [TLS Allowed CN = \lt{}string list\gt{}] +Common name attribute of allowed peer certificates. If this directive is +specified, all server certificates will be verified against this list. This +can be used to ensure that only the CA-approved Director may connect. +This directive may be specified more than once. + +\item [TLS CA Certificate File = \lt{}Filename\gt{}] +The full path and filename specifying a +PEM encoded TLS CA certificate(s). Multiple certificates are +permitted in the file. One of \emph{TLS CA Certificate File} or \emph{TLS +CA Certificate Dir} are required in a server context if \emph{TLS +Verify Peer} (see above) is also specified, and are always required in a client +context. + +\item [TLS CA Certificate Dir = \lt{}Directory\gt{}] +Full path to TLS CA certificate directory. In the current implementation, +certificates must be stored PEM encoded with OpenSSL-compatible hashes, +which is the subject name's hash and an extension of {bf .0}. +One of \emph{TLS CA Certificate File} or \emph{TLS CA Certificate Dir} are +required in a server context if \emph{TLS Verify Peer} is also specified, +and are always required in a client context. + +\item [TLS DH File = \lt{}Directory\gt{}] +Path to PEM encoded Diffie-Hellman parameter file. If this directive is +specified, DH key exchange will be used for the ephemeral keying, allowing +for forward secrecy of communications. DH key exchange adds an additional +level of security because the key used for encryption/decryption by the +server and the client is computed on each end and thus is never passed over +the network if Diffie-Hellman key exchange is used. Even if DH key +exchange is not used, the encryption/decryption key is always passed +encrypted. This directive is only valid within a server context. + +To generate the parameter file, you +may use openssl: + +\begin{verbatim} + openssl dhparam -out dh1024.pem -5 1024 +\end{verbatim} + +\end{description} + +\section{Creating a Self-signed Certificate} +\index[general]{Creating a Self-signed Certificate } +\index[general]{Certificate!Creating a Self-signed } + +You may create a self-signed certificate for use with the Bacula TLS that +will permit you to make it function, but will not allow certificate +validation. The .pem file containing both the certificate and the key +valid for ten years can be made with the following: + +\footnotesize +\begin{verbatim} + openssl req -new -x509 -nodes -out bacula.pem -keyout bacula.pem -days 3650 +\end{verbatim} +\normalsize + +The above script will ask you a number of questions. You may simply answer +each of them by entering a return, or if you wish you may enter your own data. + +Note, however, that self-signed certificates will only work for the +outgoing end of connections. For example, in the case of the Director +making a connection to a File Daemon, the File Daemon may be configured to +allow self-signed certificates, but the certificate used by the +Director must be signed by a certificate that is explicitly trusted on the +File Daemon end. + +This is necessary to prevent ``man in the middle'' attacks from tools such +as \elink{ettercap}{http://ettercap.sourceforge.net/}. Essentially, if the +Director does not verify that it is talking to a trusted remote endpoint, +it can be tricked into talking to a malicious 3rd party who is relaying and +capturing all traffic by presenting its own certificates to the Director +and File Daemons. The only way to prevent this is by using trusted +certificates, so that the man in the middle is incapable of spoofing the +connection using his own. + +To get a trusted certificate (CA or Certificate Authority signed +certificate), you will either need to purchase certificates signed by a +commercial CA or find a friend that has setup his own CA or become a CA +yourself, and thus you can sign all your own certificates. The book +OpenSSL by John Viega, Matt Mesier \& Pravir Chandra from O'Reilly explains +how to do it, or you can read the documentation provided in the Open-source +PKI Book project at Source Forge: \elink{ +http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm} +{http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}. +Note, this link may change. + +The program TinyCA has a very nice Graphical User Interface +that allows you to easily setup and maintain your own CA. +TinyCA can be found at +\elink{http://tinyca.sm-zone.net/}{http://tinyca.sm-zone.net/}. + + +\section{Getting a CA Signed Certificate} +\index[general]{Certificate!Getting a CA Signed } +\index[general]{Getting a CA Signed Certificate } + +The process of getting a certificate that is signed by a CA is quite a bit +more complicated. You can purchase one from quite a number of PKI vendors, but +that is not at all necessary for use with Bacula. To get a CA signed +certificate, you will either need to find a friend that has setup his own CA +or to become a CA yourself, and thus you can sign all your own certificates. +The book OpenSSL by John Viega, Matt Mesier \& Pravir Chandra from O'Reilly +explains how to do it, or you can read the documentation provided in the +Open-source PKI Book project at Source Forge: +\elink{ +http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm} +{http://ospkibook.sourceforge.net/docs/OSPKI-2.4.7/OSPKI-html/ospki-book.htm}. +Note, this link may change. + +\section{Example TLS Configuration Files} +\index[general]{Example!TLS Configuration Files} +\index[general]{TLS Configuration Files} + +Landon has supplied us with the TLS portions of his configuration +files, which should help you setting up your own. Note, this example +shows the directives necessary for a Director to Storage daemon session. +The technique is the same between the Director and the Client and +for bconsole to the Director. + +{\bf bacula-dir.conf} +\footnotesize +\begin{verbatim} + Director { # define myself + Name = backup1-dir + ... + TLS Enable = yes + TLS Require = yes + TLS Verify Peer = yes + TLS Allowed CN = "bacula@backup1.example.com" + TLS Allowed CN = "administrator@example.com" + TLS CA Certificate File = /usr/local/etc/ssl/ca.pem + # This is a server certificate, used for incoming + # console connections. + TLS Certificate = /usr/local/etc/ssl/backup1/cert.pem + TLS Key = /usr/local/etc/ssl/backup1/key.pem + } + + Storage { + Name = File + Address = backup1.example.com + ... + TLS Require = yes + TLS CA Certificate File = /usr/local/etc/ssl/ca.pem + # This is a client certificate, used by the director to + # connect to the storage daemon + TLS Certificate = /usr/local/etc/ssl/bacula@backup1/cert.pem + TLS Key = /usr/local/etc/ssl/bacula@backup1/key.pem + } + + Client { + Name = backup1-fd + Address = server1.example.com + ... + + TLS Enable = yes + TLS Require = yes + TLS CA Certificate File = /usr/local/etc/ssl/ca.pem + } + +\end{verbatim} +\normalsize + +{\bf bacula-fd.conf} +\footnotesize +\begin{verbatim} + Director { + Name = backup1-dir + ... + TLS Enable = yes + TLS Require = yes + TLS Verify Peer = yes + # Allow only the Director to connect + TLS Allowed CN = "bacula@backup1.example.com" + TLS CA Certificate File = /usr/local/etc/ssl/ca.pem + # This is a server certificate. It is used by connecting + # directors to verify the authenticity of this file daemon + TLS Certificate = /usr/local/etc/ssl/server1/cert.pem + TLS Key = /usr/local/etc/ssl/server1/key.pem + } + + FileDaemon { + Name = backup1-fd + ... + # you need these TLS entries so the SD and FD can + # communicate + TLS Enable = yes + TLS Require = yes + + TLS CA Certificate File = /usr/local/etc/ssl/ca.pem + TLS Certificate = /usr/local/etc/ssl/server1/cert.pem + TLS Key = /usr/local/etc/ssl/server1/key.pem +} +\end{verbatim} +\normalsize + +{\bf bacula-sd.conf} +\footnotesize +\begin{verbatim} + Storage { # definition of myself + Name = backup1-sd + ... + # These TLS configuration options are used for incoming + # file daemon connections. Director TLS settings are handled + # below. + TLS Enable = yes + TLS Require = yes + # Peer certificate is not required/requested -- peer validity + # is verified by the storage connection cookie provided to the + # File Daemon by the director. + TLS Verify Peer = no + TLS CA Certificate File = /usr/local/etc/ssl/ca.pem + # This is a server certificate. It is used by connecting + # file daemons to verify the authenticity of this storage daemon + TLS Certificate = /usr/local/etc/ssl/backup1/cert.pem + TLS Key = /usr/local/etc/ssl/backup1/key.pem + } + + # + # List Directors who are permitted to contact Storage daemon + # + Director { + Name = backup1-dir + ... + TLS Enable = yes + TLS Require = yes + # Require the connecting director to provide a certificate + # with the matching CN. + TLS Verify Peer = yes + TLS Allowed CN = "bacula@backup1.example.com" + TLS CA Certificate File = /usr/local/etc/ssl/ca.pem + # This is a server certificate. It is used by the connecting + # director to verify the authenticity of this storage daemon + TLS Certificate = /usr/local/etc/ssl/backup1/cert.pem + TLS Key = /usr/local/etc/ssl/backup1/key.pem + } +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/concepts/translate_images.pl b/docs/manuals/fr/concepts/translate_images.pl new file mode 100755 index 00000000..c7225118 --- /dev/null +++ b/docs/manuals/fr/concepts/translate_images.pl @@ -0,0 +1,185 @@ +#!/usr/bin/perl -w +# +use strict; + +# Used to change the names of the image files generated by latex2html from imgxx.png +# to meaningful names. Provision is made to go either from or to the meaningful names. +# The meaningful names are obtained from a file called imagename_translations, which +# is generated by extensions to latex2html in the make_image_file subroutine in +# bacula.perl. + +# Opens the file imagename_translations and reads the contents into a hash. +# The hash is creaed with the imgxx.png files as the key if processing TO +# meaningful filenames, and with the meaningful filenames as the key if +# processing FROM meaningful filenames. +# Then opens the html file(s) indicated in the command-line arguments and +# changes all image references according to the translations described in the +# above file. Finally, it renames the image files. +# +# Original creation: 3-27-05 by Karl Cunningham. +# Modified 5-21-05 to go FROM and TO meaningful filenames. +# +my $TRANSFILE = "imagename_translations"; +my $path; + +# Loads the contents of $TRANSFILE file into the hash referenced in the first +# argument. The hash is loaded to translate old to new if $direction is 0, +# otherwise it is loaded to translate new to old. In this context, the +# 'old' filename is the meaningful name, and the 'new' filename is the +# imgxx.png filename. It is assumed that the old image is the one that +# latex2html has used as the source to create the imgxx.png filename. +# The filename extension is taken from the file +sub read_transfile { + my ($trans,$direction) = @_; + + if (!open IN,"<$path$TRANSFILE") { + print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n"; + print " Image filename translation aborted\n\n"; + exit 0; + } + + while () { + chomp; + my ($new,$old) = split(/\001/); + + # Old filenames will usually have a leading ./ which we don't need. + $old =~ s/^\.\///; + + # The filename extension of the old filename must be made to match + # the new filename because it indicates the encoding format of the image. + my ($ext) = $new =~ /(\.[^\.]*)$/; + $old =~ s/\.[^\.]*$/$ext/; + if ($direction == 0) { + $trans->{$new} = $old; + } else { + $trans->{$old} = $new; + } + } + close IN; +} + +# Translates the image names in the file given as the first argument, according to +# the translations in the hash that is given as the second argument. +# The file contents are read in entirely into a string, the string is processed, and +# the file contents are then written. No particular care is taken to ensure that the +# file is not lost if a system failure occurs at an inopportune time. It is assumed +# that the html files being processed here can be recreated on demand. +# +# Links to other files are added to the %filelist for processing. That way, +# all linked files will be processed (assuming they are local). +sub translate_html { + my ($filename,$trans,$filelist) = @_; + my ($contents,$out,$this,$img,$dest); + my $cnt = 0; + + # If the filename is an external link ignore it. And drop any file:// from + # the filename. + $filename =~ /^(http|ftp|mailto)\:/ and return 0; + $filename =~ s/^file\:\/\///; + # Load the contents of the html file. + if (!open IF,"<$path$filename") { + print "WARNING: Cannot open $path$filename for reading\n"; + print " Image Filename Translation aborted\n\n"; + exit 0; + } + + while () { + $contents .= $_; + } + close IF; + + # Now do the translation... + # First, search for an image filename. + while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) { + $contents = $'; + $out .= $` . $&; + + # The next thing is an image name. Get it and translate it. + $contents =~ /^(.*?)\"/s; + $contents = $'; + $this = $&; + $img = $1; + # If the image is in our list of ones to be translated, do it + # and feed the result to the output. + $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img})); + $out .= $this; + } + $out .= $contents; + + # Now send the translated text to the html file, overwriting what's there. + open OF,">$path$filename" or die "Cannot open $path$filename for writing\n"; + print OF $out; + close OF; + + # Now look for any links to other files and add them to the list of files to do. + while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) { + $out = $'; + $dest = $1; + # Drop an # and anything after it. + $dest =~ s/\#.*//; + $filelist->{$dest} = '' if $dest; + } + return $cnt; +} + +# REnames the image files spefified in the %translate hash. +sub rename_images { + my $translate = shift; + my ($response); + + foreach (keys(%$translate)) { + if (! $translate->{$_}) { + print " WARNING: No destination Filename for $_\n"; + } else { + $response = `mv -f $path$_ $path$translate->{$_} 2>&1`; + $response and print "ERROR from system $response\n"; + } + } +} + +################################################# +############# MAIN ############################# +################################################ + +# %filelist starts out with keys from the @ARGV list. As files are processed, +# any links to other files are added to the %filelist. A hash of processed +# files is kept so we don't do any twice. + +# The first argument must be either --to_meaningful_names or --from_meaningful_names + +my (%translate,$search_regex,%filelist,%completed,$thisfile); +my ($cnt,$direction); + +my $arg0 = shift(@ARGV); +$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or + die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n"; + +$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1; + +(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n"; + +# Use the first argument to get the path to the file of translations. +my $tmp = $ARGV[0]; +($path) = $tmp =~ /(.*\/)/; +$path = '' unless $path; + +read_transfile(\%translate,$direction); + +foreach (@ARGV) { + # Strip the path from the filename, and use it later on. + if (s/(.*\/)//) { + $path = $1; + } else { + $path = ''; + } + $filelist{$_} = ''; + + while ($thisfile = (keys(%filelist))[0]) { + $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile})); + delete($filelist{$thisfile}); + $completed{$thisfile} = ''; + } + print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n"; +} + +rename_images(\%translate); diff --git a/docs/manuals/fr/concepts/tutorial.tex b/docs/manuals/fr/concepts/tutorial.tex new file mode 100644 index 00000000..389a5a61 --- /dev/null +++ b/docs/manuals/fr/concepts/tutorial.tex @@ -0,0 +1,1392 @@ +%% +%% + +\chapter{Une br\`eve documentation} +\label{_ChapterStart1} +\index[general]{Une br\`eve documentation} +\index[general]{Documentation!br\`eve } + +Ce chapitre vous guidera \`a travers les \'etapes n\'ecessaires pour ex\'ecuter Bacula. +Pour cela, nous supposons que vous avez install\'e Bacula, peut \^etre dans un simple +r\'epertoire comme le d\'ecrit le chapitre pr\'ec\'edent, auquel cas vous pouvez ex\'ecuter +Bacula sans \^etre root pour ces tests. Nous supposons d'autre part que vous n'avez +pas modifi\'e les fichiers de configuration. Dans le cas contraire, nous vous +recommandons de d\'esinstaller Bacula et de le r\'einstaller sans rien modifier. Les +exemples de ce chapitre utilisent les fichiers de configuration par d\'efaut, et +cr\'eent les volumes dans le r\'epertoire {\bf /tmp} de votre disque. De plus, les +donn\'ees sauvegard\'ees seront celle du r\'epertoire des sources de Bacula o\`u vous +l'avez compil\'e. Par cons\'equent, tous les {\it daemons} peuvent \^etre ex\'ecut\'es +sans les droits root pour ces tests. Notez bien qu'en production, vos File +Daemons devront \^etre ex\'ecut\'es en tant que root. Voyez le chapitre sur la +s\'ecurit\'e pour plus d'informations sur ce sujet. + +Voici les \'etapes que nous suivrons : + +\begin{enumerate} +\item cd \lt{}install-directory\gt{} +\item D\'emarrer la base de donn\'ees (si vous utilisez MySQL ou PostgreSQL) +\item D\'emarrer les {\it daemons} avec {\bf ./bacula start} +\item Lancer le programme Console pour interagir avec le Director +\item Lancer un job +\item Lorsqu'un volume est plein, le d\'emonter, s'il s'agit d'une cartouche, en + \'etiqueter une nouvelle et poursuivre. Dans ce chapitre, nous n'\'ecrirons que sur + des volumes fichier, aussi vous n'avez pas \`a vous inqui\'eter au sujet des + cartouches pour le moment. +\item Tester la restauration de quelques fichiers depuis le volume fraichement \'ecrit + pour s'assurer de la validit\'e de la sauvegarde et qu'il est possible de restaurer. + Mieux vaut essayer avant qu'un d\'esastre ne survienne... +\item Ajouter un second client. + \end{enumerate} + +Chacune de ces \'etapes est d\'ecrite en d\'etail ci-dessous. + +\section{Avant d'ex\'ecuter Bacula} +\index[general]{Bacula!Avant d'ex\'ecuter} +\index[general]{Avant d'ex\'ecuter Bacula} +\addcontentsline{toc}{section}{Avant d'ex\'ecuter Bacula} + +Avant d'utiliser Bacula pour la premi\`ere fois en production, nous vous recommandons +d'ex\'ecuter la commande {\bf test} du programme {\bf btape} ainsi qu'il est d\'ecrit +dans le chapitre \ilink{Programmes utilitaires}{btape} de ce manuel. +Ce programme vous aidera \`a vous assurer que votre lecteur de bandes fonctionne +correctement avec Bacula. Si vous avez un lecteur moderne de marque HP, Sony, ou +Quantum DDS ou DLT qui fonctionne sous Linux ou Solaris, vous pouvez probablement +vous dispenser de faire ce test car Bacula est bien test\'e avec ces lecteurs et ces +syst\`emes. Dans tous les autres cas, vous \^etes {\bf fortement} encourag\'e \`a +ex\'ecuter les tests avant de poursuivre. {\bf btape} dispose aussi d'une commande +{\bf fill} qui tente de reproduire le comportement de Bacula lorsqu'il remplit +une cartouche et qu'il poursuit son \'ecriture sur la suivante. Vous devriez +songer \`a faire ce test, sachez cependant qu'il peut \^etre long (environ +4 heures sur mon lecteur) de remplir une cartouche de haute capacit\'e. + +\section{D\'emarrer la base de donn\'ees} +\label{StartDB} +\index[general]{D\'emarrer la base de donn\'ees} +\index[general]{base de donn\'ees!D\'emarrer la } +\addcontentsline{toc}{section}{D\'emarrer la base de donn\'ees} + +Si vous utilisez MySQL ou PostgreSQL pour votre catalogue Bacula, vous devez +d\'emarrer la base de donn\'ees avant d'essayer de lancer un job pour \'eviter +d'obtenir des messages d'erreur au d\'emarrage de Bacula. J'utilise les scripts +{\bf startmysql} et {\bf stopmysql} pour d\'emarrer mon MySQL local. Notez que si +vous utilisez SQLite, vous n'aurez pas \`a utiliser {\bf startmysql} ou {\bf stopmysql}. +Si vous utilisez ceci en production, vous souhaiterez probablement trouver +un moyen pour d\'emarrer automatiquement MySQL ou PostgreSQL apr\`es chaque +red\'emarrage du syst\`eme. + +Si vous utilisez SQLite (c'est \`a dire, si vous avez sp\'ecifi\'e l'option +{\bf \verb:--:with-sqlite=xxx} de la commande {\bf ./configure}, vous n'avez rien \`a faire. +SQLite est d\'emarr\'ee automatiquement par {\bf Bacula}. + +\section{D\'emarrer les daemons} +\label{StartDaemon} +\index[general]{D\'emarrer les daemons} +\index[general]{Daemons!D\'emarrer les} +\addcontentsline{toc}{section}{D\'emarrer les daemons} + +Que vous ayez compil\'e Bacula depuis les sources ou que vous ayez install\'e les rpms, +tapez simplement : + +./bacula start + +dans votre r\'epertoire d'installation pour d\'emarrer les trois {\it daemons}. + +Le script {\bf bacula} lance le Storage Daemon, le File Daemon et le Director Daemon, qui +tournent tous trois en tant que {\it daemons} en t\^ache de fond. Si vous utilisez +la fonction de d\'emarrage automatique de Bacula, vous pouvez, au choix, lancer les +trois {\it daemons} lors du d\'emarrage, ou au contraire les lancer individuellement +avec les scripts {\bf bacula-dir}, {\bf bacula-fd}, et {\bf bacula-sd} usuellement +situ\'es dans {\bf /etc/init.d}, bien que leur localisation effective soit d\'ependante du syst\`eme +d'exploitation. + +Notez que seul le File Daemon a \'et\'e port\'e sur les syst\`emes Windows, et qu'il doit \^etre +d\'emarr\'e diff\'eramment. Veuillez consulter le chapitre +\ilink{La version Windows de Bacula}{_ChapterStart7} de ce manuel. + +Les paquetages rpm configurent les {\it daemons} pour qu'ils s'ex\'ecutent en tant +qu'utilisateur root et en tant que groupe bacula. Le processus d'installation rpm +se charge de cr\'eer le groupe bacula s'il n'existe pas sur le syst\`eme. Tout utilisateur +ajout\'e au groupe bacula h\'erite de l'acc\`es aux fichiers cr\'e\'es par les {\it daemons}. Pour +modifier ce comportement, \'editez les scripts de d\'emarrage des {\it daemons} : + +\begin{itemize} + \item /etc/bacula/bacula + \item /etc/init.d/bacula-dir + \item /etc/init.d/bacula-sd + \item /etc/init.d/bacula-fd +\end{itemize} + +puis red\'emarrez-les. + +Le chapitre +\ilink{installation}{_ChapterStart17} de ce manuel indique comment installer +les scripts de d\'emarrage automatique des {\it daemons}. + +\section{Interagir avec le Director pour l'interroger sur l'\'etat de Bacula ou lancer des jobs} +\index[general]{Jobs!Interagir avec le Director pour interroger l'\'etat de Bacula ou lancer des} +\index[general]{Interagir avec le Director pour interroger l'\'etat de Bacula ou lancer des jobs} +\addcontentsline{toc}{section}{Interagir avec le Director pour interroger l'\'etat de Bacula ou lancer des jobs} + +Pour communiquer avec le Director et pour s'enqu\'erir de l'\'etat de Bacula ou de jobs en +cours d'ex\'ecution, tapez simplement : + +./bconsole + +dans le r\'epertoire de plus haut niveau. + +Si vous avez install\'e la console GNOME et utilis\'e l'option {\bf \verb:--:enable-gnome} +de la commande configure, vous pouvez aussi utiliser la console GNOME en tapant : + +./gnome-console + +Vous pouvez aussi utiliser le programme wxWidgets {\bf bwx-console}. + +Pour simplifier, nous ne d\'ecrirons ici que le programme {\bf ./bconsole}. La plus +grande partie de ce qui est d\'ecrit ici s'applique aussi aux programmes {\bf ./gnome-console} +et {\bf bwx-console}. + +La commande {\bf ./bconsole} lance le programme Console, qui se connecte au Director. +Bacula \'etant un programme r\'eseau, vous pouvez utiliser la Console depuis n'importe quelle +machine de votre r\'eseau. Cependant, la plupart du temps le Console est ex\'ecut\'ee sur la +m\^eme machine que le Director. En principe, la Console devrait produire un affichage +similaire \`a : + +\footnotesize +\begin{verbatim} +[kern@polymatou bin]$ ./bconsole +Connecting to Director lpmatou:9101 +1000 OK: HeadMan Version: 1.30 (28 April 2003) +* +\end{verbatim} +\normalsize + +L'ast\'erisque est l'invite de commande de la console. + +Tapez {\bf help} pour obtenir la liste des commandes disponibles : + +\footnotesize +\begin{verbatim} +*help + Command Description + ======= =========== + add add media to a pool + autodisplay autodisplay [on/off] -- console messages + automount automount [on/off] -- after label + cancel cancel job=nnn -- cancel a job + create create DB Pool from resource + delete delete [pool= | media volume=] + estimate performs FileSet estimate debug=1 give full listing + exit exit = quit + help print this command + label label a tape + list list [pools | jobs | jobtotals | media | + files jobid=]; from catalog + llist full or long list like list command + messages messages + mount mount + prune prune expired records from catalog + purge purge records from catalog + query query catalog + quit quit + relabel relabel a tape + release release + restore restore files + run run + setdebug sets debug level + show show (resource records) [jobs | pools | ... | all] + sqlquery use SQL to query catalog + status status [storage | client]= + time print current time + unmount unmount + update update Volume or Pool + use use catalog xxx + var does variable expansion + version print Director version + wait wait until no jobs are running +* +\end{verbatim} +\normalsize + +Pour plus de d\'etails sur les commandes de la console, consultez le chapitre +\ilink{Console}{_ConsoleChapter} de ce manuel. + +\section{ex\'ecuter un job} +\label{Running} +\index[general]{Job!ex\'ecuter un} +\index[general]{ex\'ecuter un job} +\addcontentsline{toc}{section}{Ex\'ecuter un job} + +A ce stade, nous supposons que vous avez : + +\begin{itemize} +\item Configur\'e Bacula avec la commande {\bf ./configure \verb:--:your-options} +\item Compil\'e Bacula avec la commande {\bf make} +\item Install\'e Bacula avec la commande {\bf make install} +\item Cr\'e\'e votre catalogue avec, par exemple, la commande {\bf + ./create\_sqlite\_database} +\item Cr\'e\'e les tables du catalogue avec la commande {\bf + ./make\_bacula\_tables} +\item Eventuellement \'edit\'e votre fichier {\bf bacula-dir.conf} pour le personnaliser + quelque peu. ATTENTION ! Si vous modifiez le nom du Director ou son mot de passe, + vous devez faire les modifications correspondantes dans les autres fichiers de + configuration. Il est sans dout pr\'ef\'erable, pour l'instant, de ne rien changer. +\item D\'emarr\'e Bacula avec la commande {\bf ./bacula start} +\item Invoqu\'e le programme Console avec la commande {\bf ./bconsole}. +\end{itemize} + +En outre, nous supposons pour le moment que vous utilisez les fichiers de configuration +par d\'efaut. + +Maintenant, entrez les commandes suivantes : + +\footnotesize +\begin{verbatim} +show filesets +\end{verbatim} +\normalsize + +Vous devriez obtenir quelque chose comme : + +\footnotesize +\begin{verbatim} +FileSet: name=Full Set + O M + N + I /home/kern/bacula/regress/build + N + E /proc + E /tmp + E /.journal + E /.fsck + N +FileSet: name=Catalog + O M + N + I /home/kern/bacula/regress/working/bacula.sql + N +\end{verbatim} +\normalsize + +Il s'agit d'un {\bf FileSet} pr\'ed\'efini qui sauvegardera le r\'epertoire des +sources de Bacula. Les noms de r\'epertoires qui seront r\'eellement affich\'es +devraient correspondre \`a votre configuration. Dans une perspective de tests, +nous avons choisi un r\'epertoire de taille et de complexit\'e mod\'er\'ee (environ +40 Mo). Le FileSet {\bf Catalog} est utilis\'e pour sauvegarder le catalogue +Bacula et nous ne nous y attarderons pas pour le moment. Les entr\'ees {\bf I} +sont les fichiers ou r\'epertoires qui seront inclus dans la sauvegarde, tandis +que les entr\'ees {\bf E} sont ceux qui en seront exclus, quand aux entr\'ees {\bf O}, +ce sont les options sp\'ecifi\'ees pour ce FileSet. Vous pouvez changer ce qui est +sauvegard\'e en modifiant la ligne {\bf File =} de la ressource {\bf FileSet}. + + +Il est maintenant temps de lancer votre premi\`ere sauvegarde. Nous allons +sauvegarder votre r\'epertoire sources de Bacula vers un volume File dans votre +r\'epertoire {\bf /tmp} afin de vous montrer combien c'est facile. Saisissez : + +\footnotesize +\begin{verbatim} +status dir +\end{verbatim} +\normalsize + +Vous devriez obtenir : + +\footnotesize +\begin{verbatim} +rufus-dir Version: 1.30 (28 April 2003) +Daemon started 28-Apr-2003 14:03, 0 Jobs run. +Console connected at 28-Apr-2003 14:03 +No jobs are running. +Level Type Scheduled Name +================================================================= +Incremental Backup 29-Apr-2003 01:05 Client1 +Full Backup 29-Apr-2003 01:10 BackupCatalog +==== +\end{verbatim} +\normalsize + +O\`u les dates et le nom du Director seront diff\'erents et en accord avec votre +installation. Ceci montre qu'une sauvegarde incr\'ementale est planifi\'ee pour +le job {\bf Client1} \`a 1h05, et qu'une sauvegarde full est planifi\'ee pour +le job {\bf BackupCatalog} \`a 1h10. Vous devriez remplacer le nom {\bf Client1} +par celui de votre machine, sinon vous risquez la confusion lorsque vous +ajouterez de nouveaux clients. Pour ma machine r\'eelle, j'utilise {\bf Rufus} +plut\^ot que {\bf Client1}. + +A pr\'esent, tapez : + +\footnotesize +\begin{verbatim} +status client +\end{verbatim} +\normalsize + +Vous devriez obtenir : + +\footnotesize +\begin{verbatim} +The defined Client resources are: + 1: rufus-fd +Item 1 selected automatically. +Connecting to Client rufus-fd at rufus:8102 +rufus-fd Version: 1.30 (28 April 2003) +Daemon started 28-Apr-2003 14:03, 0 Jobs run. +Director connected at: 28-Apr-2003 14:14 +No jobs running. +==== +\end{verbatim} +\normalsize + +Dans ce cas, le client se nomme {\bf rufus-fd}, votre nom sera diff\'erent, mais la +ligne qui d\'ebute par {\bf rufus-fd Version...} est produite par votre File Daemon, +nous sommes donc maintenant surs qu'il fonctionne. + +Finalement, faites de m\^eme pour votre Storage Daemon : + +\footnotesize +\begin{verbatim} +status storage +\end{verbatim} +\normalsize + +Vous devriez obtenir : + +\footnotesize +\begin{verbatim} +The defined Storage resources are: + 1: File +Item 1 selected automatically. +Connecting to Storage daemon File at rufus:8103 +rufus-sd Version: 1.30 (28 April 2003) +Daemon started 28-Apr-2003 14:03, 0 Jobs run. +Device /tmp is not open. +No jobs running. +==== +\end{verbatim} +\normalsize + +Vous noterez que le p\'eriph\'erique du Storage Daemon par d\'efaut est nomm\'e {\bf File} +et qu'il utilise le p\'eriph\'erique {\bf /tmp}, qui n'est actuellement pas ouvert. + +Maintenant, lancez un job : + +\footnotesize +\begin{verbatim} +run +\end{verbatim} +\normalsize + +Vous devriez obtenir : + +\footnotesize +\begin{verbatim} +Using default Catalog name=MyCatalog DB=bacula +A job name must be specified. +The defined Job resources are: + 1: Client1 + 2: BackupCatalog + 3: RestoreFiles +Select Job resource (1-3): +\end{verbatim} +\normalsize + +Ici, Bacula affiche la liste des trois diff\'erents jobs que vous pouvez ex\'ecuter. +Choisissez le num\'ero {\bf 1} et validez (entr\'ee). + +Vous devriez obtenir : + +\footnotesize +\begin{verbatim} +Run Backup job +JobName: Client1 +FileSet: Full Set +Level: Incremental +Client: rufus-fd +Storage: File +Pool: Default +When: 2003-04-28 14:18:57 +OK to run? (yes/mod/no): +\end{verbatim} +\normalsize + +Prenez un peu de temps pour examiner cet affichage et le comprendre. Il vous +est demand\'e de valider, modifier ou annuler l'ex\'ecution d'un job nomm\'e +{\bf Client1} avec le FileSet {\bf Full Set} que nous avons affich\'e plus haut +en incr\'emental sur votre client rufus, utilisant le p\'eriph\'erique de stockage +{\bf File} et le pool {\bf Default} \`a la date indiqu\'ee sur la ligne "When". + +Nous avons le choix de valider ({\bf yes}), modifier un ou plusieurs des +param\`etres ci-dessus ({\bf mod}), ou de ne pas ex\'ecuter le job ({\bf no}). + +Validez l'ex\'ecution du job ({\bf yes}), vous devriez imm\'ediatement obtenir +l'invite de commande de la console (un ast\'erisque). Apr\`es quelques minutes, +la commande {\bf messages} devrait produire un r\'esultat tel que : + +\footnotesize +\begin{verbatim} +28-Apr-2003 14:22 rufus-dir: Last FULL backup time not found. Doing + FULL backup. +28-Apr-2003 14:22 rufus-dir: Start Backup JobId 1, + Job=Client1.2003-04-28_14.22.33 +28-Apr-2003 14:22 rufus-sd: Job Client1.2003-04-28_14.22.33 waiting. + Cannot find any appendable volumes. +Please use the "label" command to create a new Volume for: + Storage: FileStorage + Media type: File + Pool: Default +\end{verbatim} +\normalsize + +Le premier message signale qu'aucune sauvegarde full n'a jamais \'et\'e faite, et +que par cons\'equent Bacula \'el\`eve votre incr\'ementale en une Full (ce comportement +est normal). Le second message indique que le job a d\'emarr\'e avec le JobId 1 et le +troisi\`eme message vous informe que Bacula ne peut trouver aucun volume dans le +pool Default sur lequel \'ecrire les donn\'ees du job. Ceci est normal, car nous +n'avons encore cr\'e\'e (ou \'etiquet\'e) aucun volume. Bacula vous fournit tous les d\'etails +concernant le volume dont il a besoin. + +A ce point, le job est bloqu\'e en attente d'un volume. Vous pouvez le v\'erifier +en utilisant la commande {\bf status dir}. Pour continuer, vous devez cr\'eer un +volume sur lequel Bacula pourra \'ecrire. Voici la manipulation : + +\footnotesize +\begin{verbatim} +label +\end{verbatim} +\normalsize + +Bacula devrait afficher : + +\footnotesize +\begin{verbatim} +The defined Storage resources are: + 1: File +Item 1 selected automatically. +Enter new Volume name: +\end{verbatim} +\normalsize + +Entrez un nom commen\c {c}ant par une lettre et ne contenant que des chiffres et des lettres +(p\'eriodes, tirets et soulign\'e "\_" sont aussi autoris\'es). Par exemple entrez {\bf TestVolume001}, +vous devriez obtenir : + +\footnotesize +\begin{verbatim} +Defined Pools: + 1: Default +Item 1 selected automatically. +Connecting to Storage daemon File at rufus:8103 ... +Sending label command for Volume "TestVolume001" Slot 0 ... +3000 OK label. Volume=TestVolume001 Device=/tmp +Catalog record for Volume "TestVolume002", Slot 0 successfully created. +Requesting mount FileStorage ... +3001 OK mount. Device=/tmp +\end{verbatim} +\normalsize + +Finalement, tapez la commande {\bf messages}, vous devriez obtenir quelque chose comme : + +\footnotesize +\begin{verbatim} +28-Apr-2003 14:30 rufus-sd: Wrote label to prelabeled Volume + "TestVolume001" on device /tmp +28-Apr-2003 14:30 rufus-dir: Bacula 1.30 (28Apr03): 28-Apr-2003 14:30 +JobId: 1 +Job: Client1.2003-04-28_14.22.33 +FileSet: Full Set +Backup Level: Full +Client: rufus-fd +Start time: 28-Apr-2003 14:22 +End time: 28-Apr-2003 14:30 +Files Written: 1,444 +Bytes Written: 38,988,877 +Rate: 81.2 KB/s +Software Compression: None +Volume names(s): TestVolume001 +Volume Session Id: 1 +Volume Session Time: 1051531381 +Last Volume Bytes: 39,072,359 +FD termination status: OK +SD termination status: OK +Termination: Backup OK +28-Apr-2003 14:30 rufus-dir: Begin pruning Jobs. +28-Apr-2003 14:30 rufus-dir: No Jobs found to prune. +28-Apr-2003 14:30 rufus-dir: Begin pruning Files. +28-Apr-2003 14:30 rufus-dir: No Files found to prune. +28-Apr-2003 14:30 rufus-dir: End auto prune. +\end{verbatim} +\normalsize + +Si rien ne se passe dans l'imm\'ediat, vous pouvez continuer de rentrer la +commande {\bf messages} jusqu'\`a ce que le job se termine, ou utiliser la +commande {\bf autodisplay on} afin que les messages soient affich\'es d\`es-qu'ils +sont disponibles. + +si vous faites {\bf ls -l} dans votre r\'epertoire {\bf /tmp}, vous verrez +l'\'el\'ement suivant : + +\footnotesize +\begin{verbatim} +-rw-r----- 1 kern kern 39072153 Apr 28 14:30 TestVolume001 +\end{verbatim} +\normalsize + +Il s'agit du volume File que vous venez juste d'\'ecrire, et qui contient toutes +les donn\'ees du job que vous venez d'ex\'ecuter. Si vous ex\'ecutez d'autres jobs, +il seront ajout\'es \`a la suite de ce volume, \`a moins que vous n'ayez sp\'ecifi\'e +un autre comportement. + +Vous vous demandez peut-\^etre s'il va vous falloir \'etiqueter vous m\^eme chaque +volume que Bacula sera amen\'e \`a utiliser. La r\'eponse, en ce qui concerne les +volumes disque tels que celui que nous avons utilis\'e, est non. Il est possible +de param\'etrer Bacula pour qu'il cr\'e\'ee lui m\^eme les volumes. En revanche, +pour les volumes de type cartouche, il vous faudra tr\`es probablement +\'etiqueter chaque volume que vous voulez utiliser. + +Si vous souhaitez en rester l\`a, saisissez simplement {\bf quit} dans la +console, puis stoppez Bacula avec {\bf ./bacula stop}. Pour nettoyer +votre installation des r\'esultats de vos tests, supprimez le fichier + {\bf /tmp/TestVolume001}, et r\'einitialisez votre catalogue en utilisant : + +\footnotesize +\begin{verbatim} +./drop_bacula_tables +./make_bacula_tables +\end{verbatim} +\normalsize + +Notez bien que ceci supprimera toutes les informations concernant les jobs pr\'ec\'edemment +ex\'ecut\'es et que, si c'est sans doute ce que vous souhaitez faire en fin de phase de +test, ce n'est g\'en\'eralement pas une op\'eration souhaitable en utilisation normale. + +Si vous souhaitez essayer de restaurer les fichiers que vous venez de sauvegarder, +lisez la section suivante. + +\label{restoring} + +\section{Restaurer vos fichiers} +\index[general]{Fichiers!Restaurer vos} +\index[general]{Restaurer vos fichiers} +\addcontentsline{toc}{section}{Restaurer vos fichiers} + +Si vous avez utilis\'e la configuration par d\'efaut et sauvegard\'e les sources de Bacula +comme dans la d\'emonstration ci-dessus, vous pouvez restaurer les fichiers sauvegard\'es +en saisissant les commandes suivantes dans la Console : + +\footnotesize +\begin{verbatim} +restore all +\end{verbatim} +\normalsize + +Vous obtiendrez : + +\footnotesize +\begin{verbatim} +First you select one or more JobIds that contain files +to be restored. You will be presented several methods +of specifying the JobIds. Then you will be allowed to +select which files from those JobIds are to be restored. + +To select the JobIds, you have the following choices: + 1: List last 20 Jobs run + 2: List Jobs where a given File is saved + 3: Enter list of comma separated JobIds to select + 4: Enter SQL list command + 5: Select the most recent backup for a client + 6: Select backup for a client before a specified time + 7: Enter a list of files to restore + 8: Enter a list of files to restore before a specified time + 9: Find the JobIds of the most recent backup for a client + 10: Find the JobIds for a backup for a client before a specified time + 11: Enter a list of directories to restore for found JobIds + 12: Cancel +Select item: (1-12): +\end{verbatim} +\normalsize + +Comme vous pouvez le constater, les options sont nombreuses, mais pour l'instant, +choisissez l'option {\bf 5} afin de s\'electionner la derni\`ere sauvegarde effectu\'ee. +Vous obtiendrez : + +\footnotesize +\begin{verbatim} +Defined Clients: + 1: rufus-fd +Item 1 selected automatically. +The defined FileSet resources are: + 1: 1 Full Set 2003-04-28 14:22:33 +Item 1 selected automatically. ++-------+-------+----------+---------------------+---------------+ +| JobId | Level | JobFiles | StartTime | VolumeName | ++-------+-------+----------+---------------------+---------------+ +| 1 | F | 1444 | 2003-04-28 14:22:33 | TestVolume002 | ++-------+-------+----------+---------------------+---------------+ +You have selected the following JobId: 1 +Building directory tree for JobId 1 ... +1 Job inserted into the tree and marked for extraction. +The defined Storage resources are: + 1: File +Item 1 selected automatically. +You are now entering file selection mode where you add and +remove files to be restored. All files are initially added. +Enter "done" to leave this mode. +cwd is: / +$ +\end{verbatim} +\normalsize + +(J'ai tronqu\'e l'affichage \`a droite par soucis de lisibilit\'e.) +Comme vous pouvez le constater au d\'ebut de cet affichage, Bacula conna\^it +vos clients, et puisque vous n'en avez qu'un, il est automatiquement +s\'electionn\'e. Il en va de m\^eme pour le FileSet. Bacula produit alors une +liste de tous les jobs qui constituent la sauvegarde courante. Dans le cas +pr\'esent, il n'y en a qu'un. Notez que le Storage Daemon est aussi +s\'electionn\'e automatiquement. Bacula est maintenant en mesure de produire +une {\bf arborescence} \`a partir de tous les fichiers qui ont \'et\'e +sauvegard\'es (il s'agit d'une repr\'esentation en m\'emoire de votre syst\`eme de +fichiers). A ce stade, vous pouvez utiliser les commandes {\bf cd }, {\bf ls} +et {\bf dir} pour naviguer dans l'arborescence et voir quels fichiers +peuvent \^etre restaur\'es. Par exemple, si je saisis {\bf cd /home/kern/bacula/bacula-1.30} +suivi de {\bf dir}, j'obtiens la liste de tous les fichiers du r\'epertoire source de +Bacula. Pour plus d'information sur ce sujet, veuillez consulter le chapitre +\ilink{La commande Restore}{_ChapterStart13}. + +Pour quitter, tapez simplement : + +\footnotesize +\begin{verbatim} +done +\end{verbatim} +\normalsize + +Vous obtiendrez : + +\footnotesize +\begin{verbatim} +Bootstrap records written to + /home/kern/bacula/testbin/working/restore.bsr +The restore job will require the following Volumes: + + TestVolume001 +1444 files selected to restore. +Run Restore job +JobName: RestoreFiles +Bootstrap: /home/kern/bacula/testbin/working/restore.bsr +Where: /tmp/bacula-restores +Replace: always +FileSet: Full Set +Client: rufus-fd +Storage: File +JobId: *None* +When: 2005-04-28 14:53:54 +OK to run? (yes/mod/no): +\end{verbatim} +\normalsize + +Si vous acceptez ({\bf yes}), vos fichiers seront restaur\'es vers le r\'epertoire +{\bf /tmp/bacula-restores}. Si vous pr\'ef\'erez restaurer les fichiers \`a leurs +emplacements d'origine, vous devez utiliser l'option {\bf mod} et r\'egler +explicitement le param\`etre {\bf Where} \`a vide ou "/". Nous vous conseillons de +poursuivre avec {\bf yes}. Apr\`es quelques instants, la commande {\bf messages} +devrait produire la liste des fichiers restaur\'es, ainsi qu'un r\'esum\'e du job +qui devrait ressembler \`a ceci : + +\footnotesize +\begin{verbatim} +28-Apr-2005 14:56 rufus-dir: Bacula 1.30 (28Apr03): 28-Apr-2003 14:56 +JobId: 2 +Job: RestoreFiles.2005-04-28_14.56.06 +Client: rufus-fd +Start time: 28-Apr-2005 14:56 +End time: 28-Apr-2005 14:56 +Files Restored: 1,444 +Bytes Restored: 38,816,381 +Rate: 9704.1 KB/s +FD termination status: OK +Termination: Restore OK +28-Apr-2005 14:56 rufus-dir: Begin pruning Jobs. +28-Apr-2005 14:56 rufus-dir: No Jobs found to prune. +28-Apr-2005 14:56 rufus-dir: Begin pruning Files. +28-Apr-2005 14:56 rufus-dir: No Files found to prune. +28-Apr-2005 14:56 rufus-dir: End auto prune. +\end{verbatim} +\normalsize + +Apr\`es avoir quitt\'e la Console, vous pouvez examiner les fichiers dans le +r\'epertoire {\bf /tmp/bacula-restores}, il contient l'arborescence avec tous +vos fichiers. Supprimez-le apr\`es avoir v\'erifi\'e : + +\footnotesize +\begin{verbatim} +rm -rf /tmp/bacula-restore +\end{verbatim} +\normalsize + +\section{Quitter le programme Console} +\index[general]{Programme!Quitter Console } +\index[general]{Quitter le programme Console} +\addcontentsline{toc}{section}{Quitter le programme Console} + +Saisissez simplement la commande {\bf quit}. +\label{SecondClient} + +\section{Ajouter un client} +\index[general]{Client!Ajouter } +\index[general]{Ajouter un client } +\addcontentsline{toc}{section}{Ajouter un client} + +Si vous \^etes parvenus \`a faire fonctionner tous les exemples ci-dessus, vous \^etes +sans doute pr\`et \`a ajouter un nouveau client (File Daemon), c'est \`a dire une seconde +machine que vous souhaitez sauvegarder. La seule chose \`a installer sur la nouvelle +machine est le binaire {\bf bacula-fd} (ou {\bf bacula-fd.exe} pour Windows) et son +fichier de configuration {\bf bacula-fd.conf}. Vous pouvez d\'emarrer en copiant le fichier +pr\'ec\'edemment cr\'e\'e moyennant une modification mineure pour l'adapter au nouveau client : +changez le nom de File Daemon ({\bf rufus-fd} dans l'exemple ci-dessus) en le nom +que vous avez choisi pour le nouveau client. Le mieux est d'utiliser le nom de +la machine. Par exemple : + +\footnotesize +\begin{verbatim} +... +# +# "Global" File daemon configuration specifications +# +FileDaemon { # this is me + Name = rufus-fd + FDport = 9102 # where we listen for the director + WorkingDirectory = /home/kern/bacula/working + Pid Directory = /var/run +} +... +\end{verbatim} +\normalsize + +devient : + +\footnotesize +\begin{verbatim} +... +# +# "Global" File daemon configuration specifications +# +FileDaemon { # this is me + Name = matou-fd + FDport = 9102 # where we listen for the director + WorkingDirectory = /home/kern/bacula/working + Pid Directory = /var/run +} +... +\end{verbatim} +\normalsize + +O\`u {\bf rufus-fd} est devenu {\bf matou-fd} (je ne montre qu'une partie du fichier). +Le choix des noms vous appartient. Pour l'instant, je vous recommande de ne rien changer +d'autre. Plus tard, vous changerez le mot de passe. + +Installez cette configuration sur votre seconde machine. Il vous faut maintenant +ajouter quelques lignes \`a votre {\bf bacula-dir.conf} pour d\'efinir le nouveau +File Daemon. En vous basant sur l'exemple initial qui devrait \^etre install\'e +sur votre syst\`eme, ajoutez les lignes suivantes (essentiellement, une copie des lignes +existantes avec seulement les noms modifi\'es) \`a votre {\bf bacula-dir.conf} : + +\footnotesize +\begin{verbatim} +# +# Define the main nightly save backup job +# By default, this job will back up to disk in /tmp +Job { + Name = "Matou" + Type = Backup + Client = matou-fd + FileSet = "Full Set" + Schedule = "WeeklyCycle" + Storage = File + Messages = Standard + Pool = Default + Write Bootstrap = "/home/kern/bacula/working/matou.bsr" +} +# Client (File Services) to backup +Client { + Name = matou-fd + Address = matou + FDPort = 9102 + Catalog = MyCatalog + Password = "xxxxx" # password for + File Retention = 30d # 30 days + Job Retention = 180d # six months + AutoPrune = yes # Prune expired Jobs/Files +} +\end{verbatim} +\normalsize + +Assurez-vous que le param\`etre Address de la ressource Storage a pour valeur +le nom pleinement qualifi\'e et non quelque chose comme "localhost". L'adresse +sp\'ecifi\'ee est envoy\'ee au client et doit \^etre un nom pleinement qualifi\'e. Si vous +utilisez "localhost", l'adresse du Storage Daemon ne sera pas r\'esolue +correctement, il en r\'esultera un {\it timeout} lorsque le File Daemon +\'echouera \`a connecter le Storage Daemon. + +Il n'y a rien d'autre \`a faire. J'ai copi\'e les ressources existantes pour cr\'eer +un second job (Matou) pour sauvegarder le second client (matou-fd). le client +se nomme {\bf matou-fd} et le job {\bf Matou}, le fichier bootstrap est modifi\'e +mais tout le reste est inchang\'e. Ceci signifie que Matou sera sauvegard\'e +avec la m\^eme planification sur les m\^emes cartouches. Vous pourrez changer ceci +plus tard, pour le moment, restons simples. + +La seconde modification consiste en l'ajout d'une nouvelle ressource Client +qui d\'efinit {\bf matou-fd} et qui a l'adresse correcte {\bf matou} (mais dans +la vraie vie, vous pouvez avoir besoin d'un nom pleinement qualifi\'e ou d'une +adresse IP. J'ai aussi conserv\'e le m\^eme mot de passe (xxxxx dans l'exemple). + +A ce stade, il suffit de red\'emarrer Bacula pour qu'il prenne en compte vos +modifications. L'invite que vous avez vu plus haut devrait maintenant +inclure la nouvelle machine. + +Pour une utilisation en production vous voudrez probablement utiliser +plusieurs pools et diff\'erentes planifications. Il vous appartient de faire les +adaptations qui seyent \`a vos besoins. Dans tous les cas, n'oubliez pas de +changer les mots de passe dans les fichiers de configuration du Director et +du Client pour des raisons de s\'ecurit\'e. + +Vous trouverez des astuces importantes concernant le changement des noms et mots de +passe, ainsi qu'un diagramme d\'ecrivant leurs correspondances dans la section +\ilink{Erreurs d'authentification}{AuthorizationErrors} du chapitre FAQ de ce manuel. + +\section{Lorsque la cartouche est pleine} +\label{FullTape} +\index[general]{pleine!Lorsque la cartouche } +\index[general]{Lorsque la cartouche est pleine} +\addcontentsline{toc}{section}{Lorsque la cartouche est pleine} +Si vous avez planifi\'e votre job, il viendra un moment o\`u la cartouche sera pleine +et o\`u {\bf Bacula} ne pourra continuer. Dans ce cas, Bacula vous enverra un message +tel que : + +\begin{verbatim} +rufus-sd: block.c:337 === Write error errno=28: ERR=No space left + on device +\end{verbatim} +\normalsize + +Ceci indique que Bacula a re\c {c}u une erreur d'\'ecriture \`a cause de la carouche pleine. +Bacula va maintenant rechercher une cartouche utilisable dans le pool sp\'ecifi\'e +pour le job. Dans la situation id\'eale, vous avez r\'egl\'e correctement vos r\'etentions +et sp\'ecifi\'e que vos cartouches peuvent \^etre recycl\'ees automatiquement. Dans ce cas, +Bacula recycle automatiquement vos cartouches sorties de r\'etention et est en mesure +de r\'e\'ecrire dessus. Pour plus d'informations sur le recyclage, veuillez consulter +le chapitre \ilink{Recyclage}{_ChapterStart22} de ce manuel. Si vous constatez que +vos cartouches ne sont pas recycl\'ees correctement, consultez la section sur le +\ilink{Recyclage manuel}{manualrecycling} du chapitre Recyclage. + +Si comme moi, vous avez un tr\`es grand nombre de cartouches que vous \'etiquetez +avec la date de premi\`ere \'ecriture, si vous n'avez pas r\'egl\'e vos p\'eriodes de +r\'etention, Bacula ne trouvera pas de cartouche dans le pool et il vous enverra +un message tel que : + +\footnotesize +\begin{verbatim} +rufus-sd: Job kernsave.2002-09-19.10:50:48 waiting. Cannot find any + appendable volumes. +Please use the "label" command to create a new Volume for: + Storage: SDT-10000 + Media type: DDS-4 + Pool: Default +\end{verbatim} +\normalsize + +Ce message sera r\'ep\'et\'e une heure plus tard, puis deux heures plus tard et +ainsi de suite en doublant \`a chaque fois l'intervalle \`a concurrence d'un jour +jusqu'\`a ce que vous cr\'eiez un volume. + +Que faire dans cette situation ? + +La r\'eponse est simple : d'abord, fermez le lecteur \`a l'aide de la commande +{\bf unmount} du programme Console. Si vous n'avez qu'un lecteur, il sera +s\'electionn\'e automatiquement, sinon assurez-vous de d\'emonter celui sp\'ecifi\'e +dans le message (dans ce cas {\bf STD-10000}). + +Ensuite, retirez la cartouche du lecteur et ins\'erez-en une vierge. Notez que +sur certains lecteurs anciens, il peut \^etre n\'ecessaire d'\'ecrire une marque de +fin de fichier ({\bf mt \ -f \ /dev/nst0 \ weof}) pour \'eviter que le lecteur +ne d\'eroule toute la cartouche lorsque Bacula tente de lire le label. (NDT : j'ai un doute, la vo dit : "to prevent the drive from running away when Bacula attempts to read the label.") + +Finalement, utilisez la commande {\bf label} dans la console pour \'ecrire un +label sur le nouveau volume. la commande {\bf label} va contacter le Storage +Daemon pour qu'il \'ecrive l'\'etiquette logicielle. Si cette op\'eration se termine +correctement, le nouveau volume est ajout\'e au pool et la commande {\bf mount} est +envoy\'ee au Storage Daemon. Voyez les sections pr\'ec\'edentes de ce chapitre pour plus +de d\'etails sur l'\'etiquetage des cartouches. + +Bacula peut maintenant poursuivre le job et continuer d'\'ecrire les donn\'ees +sauvegard\'ees sur le nouveau volume. + +Si Bacula cycle sur un pool de volumes, au lieu du message ci-dessus + "Cannot find any appendable volumes.", Bacula peut vous demander de +monter un volume particulier. Dans ce cas, essayez de le satisfaire. Si, pour +quelque raison, vous n'avez plus le volume, vous pouvez monter n'importe quel +autre volume du pool, pourvu qu'il soit utilisable, Bacula l'utilisera. +La commande {\bf list volumes} du programme Console permet de d\'eterminer +les volumes utilisables et ceux qui ne le sont pas. + +Si, comme moi, vous avez param\'etr\'e correctement vos p\'eriodes de r\'etention, mais +n'avez plus aucun volume libre, vous pouvez r\'e-\'etiqueter et r\'e-utiliser un volume +comme suit : + +\begin{itemize} +\item Saisissez {\bf list volumes} dans la console et s\'electionnez le volume le plus +anciens pour le r\'e-\'etiqueter. +\item Si vos p\'eriodes de r\'etention sont judicieusement choisies, le volume devrait +avoir le statut {\bf Purged}. +\item Si le statut n'est pas {\bf Purged}, il vous faut purger le catalogue des jobs \'ecrits +sur ce volume. Ceci peut \^etre fait avec la commande {\bf purge jobs volume} dans +la console. Si vous avez plusieurs pools, vous serez invit\'e \`a choisir lequel avant +de devoir saisir le VolumeName (ou MediaId). +\item Enfin, utilisez simplement la commande {\bf relabel} pour r\'e-\'etiqueter le +volume. + \end{itemize} + +Pour r\'e-\'etiqueter manuellement le volume, suivez les \'etapes suppl\'ementaire ci-dessous : + +\begin{itemize} +\item Effacez le volume du catalogue avec la commande {\bf delete volume} dans la +console (s\'electionnez le VolumeName ou le MediaId lorsque vous y \^etes invit\'e). +\item Utilisez la commande {\bf unmount} pour d\'emonter l'ancienne cartouche. +\item R\'e-\'etiquetez physiquement l'ancienne cartouche de sorte qu'elle puisse +\^etre r\'eutilis\'ee. +\item Ins\'erez l'ancienne cartouche dans le lecteur. +\item Depuis la ligne de commande, saississez : {\bf mt \ -f \ /dev/st0 \ rewind} et +{\bf mt \ -f \ /dev/st0 \ weof}, o\`u vous prendrez soin de substituer la cha\^ine d\'esignant + votre lecteur \`a {\bf /dev/st0}. +\item Utilisez la commande {\bf label} dans la console pour \'ecrire une nouvelle +\'etiquette Bacula sur votre cartouche. +\item Utilisez la commande {\bf mount}, si ce n'est pas r\'ealis\'e automatiquement, afin +que Bacula commence \`a utiliser la cartouche fraichement \'etiquet\'ee. +\end{itemize} + +\section{D'autres commandes utiles de la console Bacula} +\index[general]{Commands!autres commandes utiles de la console Bacula} +\index[general]{autres commandes utiles de la console Bacula} +\addcontentsline{toc}{section}{D'autres commandes utiles de la console Bacula} + +\begin{description} + +\item [status dir] + \index[console]{status dir } + Affiche un \'etat de tous les jobs en cours d'ex\'ecution ainsi que tous les + jobs programm\'es dans les prochine 24 heures + +\item [status] + \index[console]{status } + Le programme Console vous invite \`a s\'electionner un {\it daemon}, puis + il s'enquiert de l'\'etat de ce {\it daemon}. + +\item [status jobid=nn] + \index[console]{status jobid } + Affiche un \'etat du JobId nn s'il est en cours d'ex\'ecution. Le Storage + Daemon est aussi contact\'e pour produire un \'etat du job. + +\item [list pools] + \index[console]{list pools } + Affiche la liste des pools d\'efinis dans le catalogue. + +\item [list media] + \index[console]{list media } + Affiche la liste des m\'edia d\'efinis dans le catalogue. + +\item [list jobs] + \index[console]{list jobs } + Affiche la liste de tous les jobs enregistr\'es dans le catalogue et squi ont \'et\'e + ex\'ecut\'es. + +\item [list jobid=nn] + \index[console]{list jobid } + Affiche le JobId nn depuis le catalogue. + +\item [list jobtotals] + \index[console]{list jobtotals } + Affiche les totaux pour tous le jobs du catalogue. + +\item [list files jobid=nn] + \index[console]{list files jobid } + Affiche la liste des fichiers sauvegard\'es pour le JobId nn. + +\item [list jobmedia] + \index[console]{list jobmedia } + Affiche des informations relatives aux m\'edia utilis\'es pour chaque job ex\'ecut\'e. + +\item [messages] + \index[console]{messages } + Affiche tous les messages redirig\'es vers la console. + +\item [unmount storage=storage-name] + \index[console]{unmount storage } + D\'emonte le lecteur associ\'e au p\'eriph\'erique de stockage d\'esign\'e par + {\bf storage-name} s'il n'est pas en cours d'utilisation. Cette commande + est utile si vous souhaitez que Bacula lib\`ere le lecteur. + +\item [mount storage=storage-name] + \index[sd]{mount storage } + Le lecteur associ\'e au p\'eriph\'erique de stockage est mont\'e \`a nouveau. Lorsque + Bacula atteint la fin d'un volume et vous demande d'en monter un nouveau, + vous devez utiliser cette commande apr\`es avoir introduit une nouvelle + cartouche dans le lecteur. En effet, c'est le signal qui indique \`a Bacula + qu'il peut commencer \`a lire ou \'ecrire sur la cartouche. + +\item [quit] + \index[sd]{quit } + Permet de quitter le programme Console. +\end{description} + +La plupart des commandes cit\'ees ci-dessus, \`a l'exception de {\bf list}, +vous invitent \`a compl\'eter la liste des arguments fournis si vous +vous contentez d'entrer le nom de la commande. + +\section{D\'ebugger la sortie des daemons} +\index[general]{D\'ebugger sortie daemons} +\index[general]{Output!D\'ebugger daemons} +\addcontentsline{toc}{section}{D\'ebugger la sortie des daemons} + +Si vous voulez d\'ebugger la sortie des {\it daemons} en cours d'ex\'ecution, +lancez-les, depuis le r\'epertoire d'installation, comme suit : + +\footnotesize +\begin{verbatim} +./bacula start -d100 +\end{verbatim} +\normalsize + +Cette possibilit\'e peut vous fournir une aide pr\'ecieuse si vos {\it daemons} +ne d\'emarrent pas correctement. Normalement, la sortie des {\it daemons} est +dirig\'ee vers le p\'eriph\'erique NULL, avec un niveau de d\'ebuggage sup\'erieur \`a +z\'ero, elle est dirig\'ee vers le terminal de lancement. + +Pour stopper les trois {\it daemons}, tapez simplement : + +\footnotesize +\begin{verbatim} +./bacula stop +\end{verbatim} +\normalsize + +dans le r\'epertoire d'installation. + +L'ex\'ecution de {\bf bacula stop} peut signaler des pids non trouv\'es. C'est Ok, +sp\'ecialement si l'un des {\bf bacula stop} est mort, ce qui est tr\`es rare. + +Pour faire une sauvegarde compl\`ete (Full) du syst\`eme, chaque File Daemon doit +\^etre ex\'ecut\'e en tant que root afin d'avoir les permissions requises pour acc\'eder +\`a tous les fichiers. Les autres {\it daemons} n'ont pas besoin des privil\`eges +root. Cependant, le Storage Daemon doit \^etre capable d'acc\'eder aux lecteurs, ce qui +Sur beaucoup de syst\`emes, n'est possible que pour root. Vous pouvez, au choix, +ex\'ecuter le Storage Daemon en tant que root, ou changer les permissions sur les +lecteurs pour autoriser les acc\`es non-root. MySQL et PostgreSQL peuvent \^etre +install\'es et ex\'ecut\'es avec un userid quelconque, les privil\`eges root ne sont pas +requis. + +\section{Soyez patient lorsque vous d\'emarrez les {\it daemons} ou montez des +cartouches vierges} +\index[general]{Soyez patient lorsque vous d\'emarrez les {\it daemons} ou montez des +cartouches vierges} +\index[general]{Cartouches!Soyez patient lorsque vous d\'emarrez les {\it daemon}s ou montez} +\addcontentsline{toc}{section}{Soyez patient lorsque vous d\'emarrez les {\it daemon}s +ou montez des cartouches vierges} + +Lorsque vous lancez les {\it daemons} Bacula, le Storage Daemon tente d'ouvrir +tous les p\'eriph\'eriques de stockage d\'efinis et de v\'erifier le volumes courrament +mont\'es. Il n'accepte aucune connection de la console tant que tous les p\'eriph\'eriques +n'ont pas \'et\'e v\'erifi\'es. Une cartouche qui a \'et\'e utilis\'e pr\'ec\'edemment doit \^etre +rembobin\'ee, ce qui, sur certain lecteurs, peut prendre plusieurs minutes. +Par cons\'equent, vous devriez faire preuve d'un peu de patience lorsue vous +tentez de contacter le Storage Daemon pour la premi\`ere fois apr\`es le +lancement de Bacula. Si vous avez un acc\`es visuel \`a votre lecteur, celui-ci +devrait \^etre pr\`et \`a l'emploi lorsque son t\'emoin lumineux cesse de clignoter. + +Les m\^emes consid\'erations s'appliquent si vous avez mont\'e une cartouche vierge +dans un lecteur tels qu'un HP DLT. Il peut s'\'ecouler une \`a deux minutes avant +que le lecteur se rende compte que la cartouche est vierge. Si vous tentez +de la monter pendant cette p\'eriode, il est probable que vous aller geler votre +pilote SCSI (c'est le cas sur mon syst\`eme RedHat). Par cons\'equent, nous vous +enjoignons une fois encore \`a \^etre patient lors de l'insertion de cartouches vierges. +Laissez le lecteur s'initialiser avant de tenter d'y acc\'eder. + +\section{Probl\`emes de connection du FD vers le SD} +\index[general]{Probl\`emes de connection du FD vers le SD } +\index[general]{SD!Probl\`emes de connection du FD vers le} +\addcontentsline{toc}{section}{Probl\`emes de connection du FD vers le SD} + +Si l'un ou plusieurs de vos File Daemons rencontre des difficult\'es \`a se connecter +au Storage Daemon, c'est tr\`es probablement que vous n'avez pas utilis\'e un nom +pleinement qualifi\'e pour la directive {\bf Address} de la ressource Storage +du fichier de configuration du Director. Le r\'esolveur de la machine cliente +(celle qui ex\'ecute le FD) doit \^etre capable de r\'esoudre le nom que vous avez +sp\'ecifi\'e dans cette directive en une adresse IP. Un exemple d'adresse ne +fonctionnant pas est {\bf localhost}. Un exemple qui pourrait fonctionner : +{\bf megalon}. Un exemple qui a encore plus de chances de fonctionner : +{\bf magalon.mydomain.com}. Sur les syst\`emes Win32, si vous ne disposez pas d'un +bon r\'esolveur (c'est souvent le cas sur Win98), vous pouvez essayer en utilisant +une adresse IP plut\^ot qu'un nom. + +Si votre adresse est correcte, assurez vous qu'aucun autre programme n'utilise +le port 9103 sur la machine qui h\'eberge le Storage Daemon. Les num\'eros de ports +de Bacula sont autoris\'es par l'IANA, et ne devraient donc pas \^etre utilis\'es par +d'autres programmes, mais il semble que certaines imprimantes HP les utilisent. +Ex\'ecutez la commande {\bf netstat -a} sur la machine qui h\'eberge le Storage +Daemon pour d\'eterminer qui utilise le port 9103 (utilis\'e pour les communications +du FD vers le SD). + +\section{Options en ligne de commande des Daemons} +\index[general]{Options en ligne de commande des Daemons} +\index[general]{Options!en ligne de commande des Daemons} +\addcontentsline{toc}{section}{Options en ligne de commande des Daemons} + +Chacun des trois {\it daemons} (Director, File, Storage) acceptent quelques options +sur la ligne de commande. En g\'en\'eral, chacun d'entre eux, de m\^eme que le +programme Console, admet les otpions suivantes : + + +\begin{description} + +\item [-c \lt{}file\gt{}] + \index[sd]{-c \lt{}file\gt{} } + D\'efinit le fichier de configuration \`a utiliser. La valeur par d\'efaut est le +nom du {\it daemon} suivi de {\bf conf}, par exemple {\bf bacula -dir.conf} pour +le Director, {\bf bacula-fd} pour le File Daemon, et {\bf bacula-sd.conf} pour +le Storage Daemon. + +\item [-d nn] + \index[sd]{-d nn } + Fixe le niveau de d\'ebuggage \`a la valeur {\bf nn}. Les niveaux les plus \'elev\'e +permettent d'afficher plus d'information sur STDOUT concernant ce que le {\it daemon} est +en train de faire. + +\item [-f] + Ex\'ecute le {\it daemon} en arri\`ere plan. Cette option est requise pour ex\'ecuter les +{\it daemon}s avec le debugger. + +\item [-s] + Ne pas capturer les signaux. Cette option est requise pour ex\'ecuter les +{\it daemon}s avec le debugger. + +\item [-t] + Lire les fichiers de configuration et afficher les messages d'erreur, et quitter +imm\'ediatement. Tr\`es utile pour tester la syntaxe de nouveaux fichiers de configuration. + +\item [-v] + Mode verbeux. Utile pour rendre les messages d'erreur et d'information plus complets. + +\item [-?] + Affiche la version et la liste des options. + \end{description} + +Le Director a les options sp\'ecifiques suivantes : + +\begin{description} + +\item [-r \lt{}job\gt{}] + \index[fd]{-r \lt{}job\gt{} } + Ex\'ecute le job d\'esign\'e imm\'ediatement. Ceci ne devrait servir qu'\`a des fins +de d\'ebuggage. +\end{description} + +Le File Daemon les options sp\'ecifiques suivantes : + +\begin{description} + +\item [-i] + Suppose que le {\it daemon} est appel\'e par {\bf inetd} ou {\bf xinetd}. Dans ce cas, +le {\it daemon} suppose qu'une connection est d\'ej\`a \'etablie et qu'elle est pass\'ee en tant que +STDIN. Le {\it daemon} s'arr\`ete d\`es que la connection se termine. +\end{description} + +Le Storage Daemon n'a pas d'options sp\'ecifiques. + +Le programme Console n'a pas d'options sp\'ecifiques. + +\section{Cr\'eer un Pool} +\label{Pool} +\index[general]{Pool!Cr\'eer un } +\index[general]{Cr\'eer un Pool } +\addcontentsline{toc}{section}{Cr\'eer un Pool} + +La cr\'eation de pool est automatique au d\'emarrage de Bacula, aussi si vous +comprenez d\'ej\`a le concept de pools et leur fonctionnement, vous pouvez passer +\`a la section suivante. + +Lorsque vous ex\'ecutez un job, Bacula doit d\'eterminer quel volume utiliser pour +sauvegarder le FileSet. Plut\^ot que de sp\'ecifier un volume directement, vous +sp\'ecifiez l'ensemble de volumes dans lequel vous autorisez Bacula \`a puiser +lorsqu'il lui faut un volume pour \'ecrire les donn\'ees sauvegard\'ees. D\`es lors, Bacula +se charge de s\'electionner le premier volume utilisable dans le pool appropri\'e +au p\'eriph\'erique que vous avez sp\'ecifi\'e pour le job ex\'ecut\'e. Lorsqu'un volume est +plein, Bacula change son VolStatus de {\bf Append} en {\bf Full}, et utilise le +volume suivant, et ainsi de de suite. S'il n'y a pas de volume utilisable, +Bacula envoie un message \`a l'op\'erateur pour r\'eclamer la cr\'eation d'un +volume appropri\'e. + +{\bf Bacula} garde trace des noms de pools, des volumes contenus dans les pools, +et de plusieurs caract\'eristiques de chacun de ces volumes. + +Lorsque Bacula d\'emarre, il s'assure que toutes les d\'efinitions de ressources Pool +ont \'et\'e enregistr\'ees dans le catalogue. Vous pouvez le v\'erifier avec la commande : + +\footnotesize +\begin{verbatim} +list pools +\end{verbatim} +\normalsize + +du programme Console, qui devrait produire quelque chose comme : + +\footnotesize +\begin{verbatim} +*list pools +Using default Catalog name=MySQL DB=bacula ++--------+---------+---------+---------+----------+-------------+ +| PoolId | Name | NumVols | MaxVols | PoolType | LabelFormat | ++--------+---------+---------+---------+----------+-------------+ +| 1 | Default | 3 | 0 | Backup | * | +| 2 | File | 12 | 12 | Backup | File | ++--------+---------+---------+---------+----------+-------------+ +* +\end{verbatim} +\normalsize + +Si vous tentez de cr\'eer un pool existant, Bacula affiche : + +\footnotesize +\begin{verbatim} +Error: Pool Default already exists. +Once created, you may use the {\bf update} command to +modify many of the values in the Pool record. +\end{verbatim} +\normalsize + +\label{Labeling} + +\section{Etiqueter vos Volumes} +\index[general]{Volumes!Etiqueter vos} +\index[general]{Etiqueter vos Volumes} +\addcontentsline{toc}{section}{Etiqueter vos Volumes} + +Bacula exige que chaque volume comporte une \'etiquette (NDT : label) logicielle. +Il existe plusieurs strat\'egies pour \'etiqueter les volumes. Celle que j'utilise +consiste \`a les \'etiqueter \`a l'aide du programme Console au fur et \`a mesure qu'ils +sont requis par Bacula. Ainsi, lorsqu'il a besoin d'un volume qu'il ne trouve pas +dans son catalogue, Bacula m'envoie un e-mail pour m'enjoindre \`a ajouter un +volume au pool. J'utilise alors la commande {\bf label} dans la console pour +\'etiqueter un nouveau volume et le d\'efinir dans le catalogue, apr\`es quoi Bacula +est en mesure de l'utiliser. Alternativement, je peux utiliser la commande +{\bf relabel} pour r\'e-\'etiquter un volume qui n'est plus utilis\'e, pourvu qu'il ait +le VolStatus {\bf Purged}. + +Une autre strat\'egie consiste \`a \'etiqueter un ensemble de volumes, et \`a les +utiliser au fur et \`a mesure que Bacula les r\'eclame. C'est le plus souvent ce qui +est fait lorsque vous cyclez sur un groupe de volumes, par exemple avec une +librairie. Pour plus de d\'etails sur le recyclage, veuillez consulter le +chapitre \ilink{Recyclage automatique des volumes}{_ChapterStart22} de ce +manuel. + +Si vous ex\'ecutez un job Bacula alors que vous n'avez pas de volumes +\'etiquet\'es dans le pool concern\'e, Bacula vous en informe, et vous pouvez les +cr\'eer "\`a la vol\'ee". Dans mon cas, j'\'etiquette mes cartouches avec la date, +par exemple : {\bf DLT-18April02}. Voyez ci-dessous pour plus de d\'etails +sur l'usage de la commande {\bf label}. + +\section{Etiquetage des volumes dans la console} +\index[general]{Etiquetage des volumes dans la console} +\index[general]{Console!Etiquetage des volumes dans la} +\addcontentsline{toc}{section}{Etiquetage des volumes dans la console} + +L'\'etiquetage des volumes se fait, en principe, avec le programme Console. + +\begin{enumerate} +\item ./bconsole +\item label + \end{enumerate} + +Si Bacula annonce que vous ne pouvez \'etiqueter une cartouche au motif qu'elle +porte d\'ej\`a une \'etiquette, d\'emontez-la avec la commande {\bf unmount}, puis +recommencez avec une cartouche vierge. + +Etand donn\'e que le support de stockage physique est diff\'erent pour chaque +p\'eriph\'erique, la commande {\bf label} vous propose une liste de ressources +Storage d\'efinies telle que celle-ci : + +\footnotesize +\begin{verbatim} +The defined Storage resources are: + 1: File + 2: 8mmDrive + 3: DLTDrive + 4: SDT-10000 +Select Storage resource (1-4): +\end{verbatim} +\normalsize + +A ce stade, vous devriez avoir une cartouche vierge dans votre lecteur +d'un type correspondant \`a la ressource Storage que vous avez s\'electionn\'e. + +Bacula vous demande le nom du volume : + +\footnotesize +\begin{verbatim} +Enter new Volume name: +\end{verbatim} +\normalsize + +S'il proteste : + +\footnotesize +\begin{verbatim} +Media record for Volume xxxx already exists. +\end{verbatim} +\normalsize + +Cela signifie que le nom de volume {\bf xxxx} que vous avez entr\'e existe d\`ej\`a +dans le catalogue. Vous pouvez afficher la liste des m\'edia d\'efinis avec la +commande {\bf list media}. Notez que la colonne LastWritten a ici \'et\'e +tronqu\'ee pour permettre un affichage propre. + +\footnotesize +\begin{verbatim} ++---------------+---------+--------+----------------+-----/~/-+------------+-----+ +| VolumeName | MediaTyp| VolStat| VolBytes | LastWri | VolReten | Recy| ++---------------+---------+--------+----------------+---------+------------+-----+ +| DLTVol0002 | DLT8000 | Purged | 56,128,042,217 | 2001-10 | 31,536,000 | 0 | +| DLT-07Oct2001 | DLT8000 | Full | 56,172,030,586 | 2001-11 | 31,536,000 | 0 | +| DLT-08Nov2001 | DLT8000 | Full | 55,691,684,216 | 2001-12 | 31,536,000 | 0 | +| DLT-01Dec2001 | DLT8000 | Full | 55,162,215,866 | 2001-12 | 31,536,000 | 0 | +| DLT-28Dec2001 | DLT8000 | Full | 57,888,007,042 | 2002-01 | 31,536,000 | 0 | +| DLT-20Jan2002 | DLT8000 | Full | 57,003,507,308 | 2002-02 | 31,536,000 | 0 | +| DLT-16Feb2002 | DLT8000 | Full | 55,772,630,824 | 2002-03 | 31,536,000 | 0 | +| DLT-12Mar2002 | DLT8000 | Full | 50,666,320,453 | 1970-01 | 31,536,000 | 0 | +| DLT-27Mar2002 | DLT8000 | Full | 57,592,952,309 | 2002-04 | 31,536,000 | 0 | +| DLT-15Apr2002 | DLT8000 | Full | 57,190,864,185 | 2002-05 | 31,536,000 | 0 | +| DLT-04May2002 | DLT8000 | Full | 60,486,677,724 | 2002-05 | 31,536,000 | 0 | +| DLT-26May02 | DLT8000 | Append | 1,336,699,620 | 2002-05 | 31,536,000 | 1 | ++---------------+---------+--------+----------------+-----/~/-+------------+-----+ +\end{verbatim} +\normalsize + +Une fois que Bacula a v\'erifi\'e que le volume n'existe pas encore, il vous +demande le pool dans lequel vous souhaitez que le volume soit cr\'e\'e. S'il +n'existe qu'un pool, il est s\'electionn\'e automatiquement. + +Si la cartouche est \'etiquet\'ee correctement, un enregistrement de volume est +aussi cr\'e\'e dans le pool. Ainsi, le nom du volume et tous ses attributs +appara\^itront lorque vous afficherez les volumes du pool. De plus, le volume +est disponible pour les sauvegardes, pourvu que le MediaType co\"¨incide avec +celui requis par le Storage Daemon. + +Lorsque vous avez \'etiquet\'e la cartouche, vous n'avez r\'epondu qu'\`a quelques +questions la concernant -- principalement son nom, et \'eventuellement le {\it Slot}. +Cependant, un enregistrement de volume dans le catalogue (connu au niveau interne +en tant qu'enregistrement Media) contient un certain nombre d'attributs. +La plupart d'entre eux sont renseign\'es selon les valeurs par d\'efaut qui ont \'et\'e +d\'efinies lors de la cr\'eation du pool (au trement dit, le pool comporte la plupart des +attributs par d\'efaut utilis\'es lors de la cr\'eation d'un volume). + +Il est aussi possible d'ajouter des media aux pools sans les \'etiqueter +physiquement. C'est la fonction de la commande {\bf add}. Pour plus +d'informations, veuillez consulterle chapitre \ilink{Console}{_ConsoleChapter} +de ce manuel. diff --git a/docs/manuals/fr/concepts/update_version b/docs/manuals/fr/concepts/update_version new file mode 100755 index 00000000..5c2e0092 --- /dev/null +++ b/docs/manuals/fr/concepts/update_version @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/concepts/update_version.in b/docs/manuals/fr/concepts/update_version.in new file mode 100644 index 00000000..2766245f --- /dev/null +++ b/docs/manuals/fr/concepts/update_version.in @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/concepts/uploaddoc b/docs/manuals/fr/concepts/uploaddoc new file mode 100755 index 00000000..02668a12 --- /dev/null +++ b/docs/manuals/fr/concepts/uploaddoc @@ -0,0 +1,11 @@ +#!/bin/sh + +ftp -i ftp.sectoor.de <out + type out +\end{verbatim} +\normalsize + +The precise path to bacula-fd depends on where it is installed. The +example above is the default used in 1.39.22 and later. +The {\bf -t} option will cause Bacula to read the configuration file, print +any error messages and then exit. the {\bf \gt{}} redirects the output to the +file named {\bf out}, which you can list with the {\bf type} command. + +If something is going wrong later, or you want to run {\bf Bacula} with a +debug option, you might try starting it as: + +\footnotesize +\begin{verbatim} + c:\Program Files\bacula\bin\bacula-fd -d 100 >out +\end{verbatim} +\normalsize + +In this case, Bacula will run until you explicitly stop it, which will give +you a chance to connect to it from your Unix/Linux server. In later versions +of Bacula (1.34 on, I think), when you start the File daemon in debug mode it +can write the output to a trace file {\bf bacula.trace} in the current +directory. To enable this, before running a job, use the console, and enter: + +\footnotesize +\begin{verbatim} + trace on +\end{verbatim} +\normalsize + +then run the job, and once you have terminated the File daemon, you will find +the debug output in the {\bf bacula.trace} file, which will probably be +located in the same directory as bacula-fd.exe. + +In addition, you should look in the System Applications log on the Control +Panel to find any Windows errors that Bacula got during the startup process. + +Finally, due to the above problems, when you turn on debugging, and specify +trace=1 on a setdebug command in the Console, Bacula will write the debug +information to the file {\bf bacula.trace} in the directory from which Bacula +is executing. + +If you are having problems with ClientRunBeforeJob scripts randomly dying, +it is possible that you have run into an Oracle bug. See bug number 622 in +the bugs.bacula.org database. The following information has been +provided by a user on this issue: + +\footnotesize +\begin{verbatim} +The information in this document applies to: + Oracle HTTP Server - Version: 9.0.4 + Microsoft Windows Server 2003 + Symptoms + When starting an OC4J instance, the System Clock runs faster, about 7 +seconds per minute. + + Cause + + + This is caused by the Sun JVM bug 4500388, which states that "Calling +Thread.sleep() with a small argument affects the system clock". Although +this is reported as fixed in JDK 1.4.0_02, several reports contradict this +(see the bug in +http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4500388). + + + Also reported by Microsoft as "The system clock may run fast when you +use the ACPI power management timer as a high-resolution counter on Windows +2000-based computers" (See http://support.microsoft.com/?id=821893) +\end{verbatim} +\normalsize + +You may wish to start the daemon with debug mode on rather than doing it +using bconsole. To do so, edit the following registry key: + +\footnotesize +\begin{verbatim} +HKEY_LOCAL_MACHINE\HARDWARE\SYSTEM\CurrentControlSet\Services\Bacula-dir +\end{verbatim} +\normalsize + +using regedit, then add -dnn after the /service option, where nn represents +the debug level you want. + +\label{Compatibility} +\section{Windows Compatibility Considerations} +\index[general]{Windows Compatibility Considerations} +\index[general]{Considerations!Windows Compatibility} + +If you are not using the VSS (Volume Shadow Copy) option described in the +next section of this chapter, and if any applications are running during +the backup and they have files opened exclusively, Bacula will not be able +to backup those files, so be sure you close your applications (or tell your +users to close their applications) before the backup. Fortunately, most +Microsoft applications do not open files exclusively so that they can be +backed up. However, you will need to experiment. In any case, if Bacula +cannot open the file, it will print an error message, so you will always +know which files were not backed up. For version 1.37.25 and greater, see +the section below on Volume Shadow Copy Service that permits backing up any +file. + +During backup, Bacula doesn't know about the system registry, so you will +either need to write it out to an ASCII file using {\bf regedit~~/e} or use a +program specifically designed to make a copy or backup the registry. + +In Bacula version 1.31 and later, we use Windows backup API calls by +default. Typical of Windows, programming these special BackupRead and +BackupWrite calls is a real nightmare of complications. The end result +gives some distinct advantages and some disadvantages. + +First, the advantages are that on WinNT/2K/XP systems, the security and +ownership information is now backed up. In addition, with the exception of +files in exclusive use by another program, Bacula can now access all system +files. This means that when you restore files, the security and ownership +information will be restored on WinNT/2K/XP along with the data. + +The disadvantage of the Windows backup API calls is that it produces +non-portable backups. That is files and their data that are backed up on +WinNT using the native API calls (BackupRead/BackupWrite) cannot be +restored on Win95/98/Me or Unix systems. In principle, a file backed up on +WinNT can be restored on WinXP, but this remains to be seen in practice +(not yet tested). In addition, the stand-alone tools such as {\bf bls} and +{\bf bextract} cannot be used to retrieve the data for those files because +those tools are not available on Windows. All restores must use the Bacula +{\bf restore} command. As of Bacula 1.39.x, thanks to Thorsten Engel, this +restriction is removed, and Bacula should be able to read non-portable +backups on any system and restore the data appropriately. However, +on a system that does not have the BackupRead/BackupWrite calls (older +Windows versions and all Unix/Linux machines), though the file data +can be restored, the Windows security and access control data will not be restored. +This means that a standard set of access permissions will be set for +such restored files. + + +As a default, Bacula backs up Windows systems using the Windows API calls. +If you want to backup data on a WinNT/2K/XP system and restore it on a +Unix/Win95/98/Me system, we have provided a special {\bf portable} option +that backs up the data in a portable fashion by using portable API calls. +See the \ilink{portable option}{portable} on the Include statement in a +FileSet resource in the Director's configuration chapter for the details on +setting this option. However, using the portable option means you may have +permissions problems accessing files, and none of the security and +ownership information will be backed up or restored. The file data can, +however, be restored on any system. + +You should always be able to restore any file backed up on Unix or Win95/98/Me +to any other system. On some systems, such as WinNT/2K/XP, you may have to +reset the ownership of such restored files. Any file backed up on WinNT/2K/XP +should in principle be able to be restored to a similar system (i.e. +WinNT/2K/XP), however, I am unsure of the consequences if the owner +information and accounts are not identical on both systems. Bacula will not +let you restore files backed up on WinNT/2K/XP to any other system (i.e. Unix +Win95/98/Me) if you have used the defaults. + +Finally, if you specify the {\bf portable=yes} option on the files you back +up. Bacula will be able to restore them on any other system. However, any +WinNT/2K/XP specific security and ownership information will be lost. + +The following matrix will give you an idea of what you can expect. Thanks to +Marc Brueckner for doing the tests: + +\addcontentsline{lot}{table}{WinNT/2K/XP Restore Portability Status} +\begin{longtable}{|l|l|p{2.8in}|} + \hline +\multicolumn{1}{|c|}{\bf Backup OS} & \multicolumn{1}{c|}{\bf Restore OS} +& \multicolumn{1}{c|}{\bf Results } \\ + \hline {WinMe} & {WinMe} & {Works } \\ + \hline {WinMe} & {WinNT} & {Works (SYSTEM permissions) } \\ + \hline {WinMe} & {WinXP} & {Works (SYSTEM permissions) } \\ + \hline {WinMe} & {Linux} & {Works (SYSTEM permissions) } \\ + \hline {\ } & {\ } & {\ } \\ + \hline {WinXP} & {WinXP} & {Works } \\ + \hline {WinXP} & {WinNT} & {Works (all files OK, but got "The data is invalid" +message) } \\ + \hline {WinXP} & {WinMe} & {Error: Win32 data stream not supported. } \\ + \hline {WinXP} & {WinMe} & {Works if {\bf Portable=yes} specified during backup.} \\ + \hline {WinXP} & {Linux} & {Error: Win32 data stream not supported. } \\ + \hline {WinXP} & {Linux} & {Works if {\bf Portable=yes} specified during backup.}\\ + \hline {\ } & {\ } & {\ } \\ + \hline {WinNT} & {WinNT} & {Works } \\ + \hline {WinNT} & {WinXP} & {Works } \\ + \hline {WinNT} & {WinMe} & {Error: Win32 data stream not supported. } \\ + \hline {WinNT} & {WinMe} & {Works if {\bf Portable=yes} specified during backup.}\\ + \hline {WinNT} & {Linux} & {Error: Win32 data stream not supported. } \\ + \hline {WinNT} & {Linux} & {Works if {\bf Portable=yes} specified during backup. }\\ + \hline {\ } & {\ } & {\ } \\ + \hline {Linux} & {Linux} & {Works } \\ + \hline {Linux} & {WinNT} & {Works (SYSTEM permissions) } \\ + \hline {Linux} & {WinMe} & {Works } \\ + \hline {Linux} & {WinXP} & {Works (SYSTEM permissions)} +\\ \hline +\end{longtable} + +Note: with Bacula versions 1.39.x and later, non-portable Windows data can +be restore to any machine. + + +\label{VSS} +\section{Volume Shadow Copy Service} +\index[general]{Volume Shadow Copy Service} +\index[general]{VSS} +In version 1.37.30 and greater, you can turn on Microsoft's Volume +Shadow Copy Service (VSS). + +Microsoft added VSS to Windows XP and Windows 2003. From the perspective of +a backup-solution for Windows, this is an extremely important step. VSS +allows Bacula to backup open files and even to interact with applications like +RDBMS to produce consistent file copies. VSS aware applications are called +VSS Writers, they register with the OS so that when Bacula wants to do a +Snapshot, the OS will notify the register Writer programs, which may then +create a consistent state in their application, which will be backed up. +Examples for these writers are "MSDE" (Microsoft database +engine), "Event Log Writer", "Registry Writer" plus 3rd +party-writers. If you have a non-vss aware application (e.g. +SQL Anywhere or probably MySQL), a shadow copy is still generated +and the open files can be backed up, but there is no guarantee +that the file is consistent. + +Bacula produces a message from each of the registered writer programs +when it is doing a VSS backup so you know which ones are correctly backed +up. + +Bacula supports VSS on both Windows 2003 and Windows XP. +Technically Bacula creates a shadow copy as soon as the backup process +starts. It does then backup all files from the shadow copy and destroys the +shadow copy after the backup process. Please have in mind, that VSS +creates a snapshot and thus backs up the system at the state it had +when starting the backup. It will disregard file changes which occur during +the backup process. + +VSS can be turned on by placing an + +\index[dir]{Enable VSS} +\index[general]{Enable VSS} +\begin{verbatim} +Enable VSS = yes +\end{verbatim} + +in your FileSet resource. + +The VSS aware File daemon has the letters VSS on the signon line that +it produces when contacted by the console. For example: +\begin{verbatim} +Tibs-fd Version: 1.37.32 (22 July 2005) VSS Windows XP MVS NT 5.1.2600 +\end{verbatim} +the VSS is shown in the line above. This only means that the File daemon +is capable of doing VSS not that VSS is turned on for a particular backup. +There are two ways of telling if VSS is actually turned on during a backup. +The first is to look at the status output for a job, e.g.: +\footnotesize +\begin{verbatim} +Running Jobs: +JobId 1 Job NightlySave.2005-07-23_13.25.45 is running. + VSS Backup Job started: 23-Jul-05 13:25 + Files=70,113 Bytes=3,987,180,650 Bytes/sec=3,244,247 + Files Examined=75,021 + Processing file: c:/Documents and Settings/kern/My Documents/My Pictures/Misc1/Sans titre - 39.pdd + SDReadSeqNo=5 fd=352 +\end{verbatim} +\normalsize +Here, you see under Running Jobs that JobId 1 is "VSS Backup Job started ..." +This means that VSS is enabled for that job. If VSS is not enabled, it will +simply show "Backup Job started ..." without the letters VSS. + +The second way to know that the job was backed up with VSS is to look at the +Job Report, which will look something like the following: +\footnotesize +\begin{verbatim} +23-Jul 13:25 rufus-dir: Start Backup JobId 1, Job=NightlySave.2005-07-23_13.25.45 +23-Jul 13:26 rufus-sd: Wrote label to prelabeled Volume "TestVolume001" on device "DDS-4" (/dev/nst0) +23-Jul 13:26 rufus-sd: Spooling data ... +23-Jul 13:26 Tibs: Generate VSS snapshots. Driver="VSS WinXP", Drive(s)="C" +23-Jul 13:26 Tibs: VSS Writer: "MSDEWriter", State: 1 (VSS_WS_STABLE) +23-Jul 13:26 Tibs: VSS Writer: "Microsoft Writer (Bootable State)", State: 1 (VSS_WS_STABLE) +23-Jul 13:26 Tibs: VSS Writer: "WMI Writer", State: 1 (VSS_WS_STABLE) +23-Jul 13:26 Tibs: VSS Writer: "Microsoft Writer (Service State)", State: 1 (VSS_WS_STABLE) +\end{verbatim} +\normalsize +In the above Job Report listing, you see that the VSS snapshot was generated for drive C (if +other drives are backed up, they will be listed on the {\bf Drive(s)="C"} You also see the +reports from each of the writer program. Here they all report VSS\_WS\_STABLE, which means +that you will get a consistent snapshot of the data handled by that writer. + +\section{VSS Problems} +\index[general]{Problems!VSS} +\index[fd] {Problems!VSS} +\index[general]{VSS Problems} +\index[fd]{VSS Problems} + +If you are experiencing problems such as VSS hanging on MSDE, first try +running {\bf vssadmin} to check for problems, then try running {\bf +ntbackup} which also uses VSS to see if it has similar problems. If so, you +know that the problem is in your Windows machine and not with Bacula. + +The FD hang problems were reported with {\bf MSDEwriter} when: +\begin{itemize} +\item a local firewall locked local access to the MSDE TCP port (MSDEwriter +seems to use TCP/IP and not Named Pipes). +\item msdtcs was installed to run under "localsystem": try running msdtcs +under networking account (instead of local system) (com+ seems to work +better with this configuration). +\end{itemize} + + +\section{Windows Firewalls} +\index[general]{Firewalls!Windows} +\index[general]{Windows Firewalls} + +If you turn on the firewalling feature on Windows (default in WinXP SP2), you +are likely to find that the Bacula ports are blocked and you cannot +communicate to the other daemons. This can be deactivated through the {\bf +Security Notification} dialog, which is apparently somewhere in the {\bf +Security Center}. I don't have this on my computer, so I cannot give the exact +details. + +The command: + +\footnotesize +\begin{verbatim} +netsh firewall set opmode disable +\end{verbatim} +\normalsize + +is purported to disable the firewall, but this command is not accepted on my +WinXP Home machine. + +\section{Windows Port Usage} +\index[general]{Windows Port Usage} +\index[general]{Usage!Windows Port} + +If you want to see if the File daemon has properly opened the port and is +listening, you can enter the following command in a shell window: + +\footnotesize +\begin{verbatim} + netstat -an | findstr 910[123] +\end{verbatim} +\normalsize + +TopView is another program that has been recommend, but it is not a +standard Win32 program, so you must find and download it from the Internet. + +\section{Windows Disaster Recovery} +\index[general]{Recovery!Windows Disaster} +\index[general]{Windows Disaster Recovery} + +We don't currently have a good solution for disaster recovery on Windows as we +do on Linux. The main piece lacking is a Windows boot floppy or a Windows boot +CD. Microsoft releases a Windows Pre-installation Environment ({\bf WinPE}) +that could possibly work, but we have not investigated it. This means that +until someone figures out the correct procedure, you must restore the OS from +the installation disks, then you can load a Bacula client and restore files. +Please don't count on using {\bf bextract} to extract files from your backup +tapes during a disaster recovery unless you have backed up those files using +the {\bf portable} option. {\bf bextract} does not run on Windows, and the +normal way Bacula saves files using the Windows API prevents the files from +being restored on a Unix machine. Once you have an operational Windows OS +loaded, you can run the File daemon and restore your user files. + +Please see +\ilink{ Disaster Recovery of Win32 Systems}{Win3233} for the latest +suggestion, which looks very promising. + +It looks like Bart PE Builder, which creates a Windows PE (Pre-installation +Environment) Boot-CD, may be just what is needed to build a complete disaster +recovery system for Win32. This distribution can be found at +\elink{http://www.nu2.nu/pebuilder/}{\url{http://www.nu2.nu/pebuilder/}}. + +\section{Windows Restore Problems} +\index[general]{Problems!Windows Restore} +\index[general]{Windows Restore Problems} +Please see the +\ilink{Restore Chapter}{Windows} of this manual for problems +that you might encounter doing a restore. + +section{Windows Backup Problems} +\index[general]{Problems!Windows Backup} +\index[general]{Windows Backup Problems} +If during a Backup, you get the message: +{\bf ERR=Access is denied} and you are using the portable option, +you should try both adding both the non-portable (backup API) and +the Volume Shadow Copy options to your Director's conf file. + +In the Options resource: +\footnotesize +\begin{verbatim} +portable = no +\end{verbatim} +\normalsize + +In the FileSet resource: +\footnotesize +\begin{verbatim} +enablevss = yes +\end{verbatim} +\normalsize + +In general, specifying these two options should allow you to backup +any file on a Windows system. However, in some cases, if users +have allowed to have full control of their folders, even system programs +such a Bacula can be locked out. In this case, you must identify +which folders or files are creating the problem and do the following: + +\begin{enumerate} +\item Grant ownership of the file/folder to the Administrators group, +with the option to replace the owner on all child objects. +\item Grant full control permissions to the Administrators group, +and change the user's group to only have Modify permission to +the file/folder and all child objects. +\end{enumerate} + +Thanks to Georger Araujo for the above information. + +\section{Windows Ownership and Permissions Problems} +\index[general]{Problems!Windows Ownership and Permissions} +\index[general]{Windows Ownership and Permissions Problems} + +If you restore files backed up from WinNT/XP/2K to an alternate directory, +Bacula may need to create some higher level directories that were not saved +(or restored). In this case, the File daemon will create them under the SYSTEM +account because that is the account that Bacula runs under as a service. As of +version 1.32f-3, Bacula creates these files with full access permission. +However, there may be cases where you have problems accessing those files even +if you run as administrator. In principle, Microsoft supplies you with the way +to cease the ownership of those files and thus change the permissions. +However, a much better solution to working with and changing Win32 permissions +is the program {\bf SetACL}, which can be found at +\elink{http://setacl.sourceforge.net/}{\url{http://setacl.sourceforge.net/}}. + +If you have not installed Bacula while running as Administrator +and if Bacula is not running as a Process with the userid (User Name) SYSTEM, +then it is very unlikely that it will have sufficient permission to +access all your files. + +Some users have experienced problems restoring files that participate in +the Active Directory. They also report that changing the userid under which +Bacula (bacula-fd.exe) runs, from SYSTEM to a Domain Admin userid, resolves +the problem. + + +\section{Manually resetting the Permissions} +\index[general]{Manually resetting the Permissions} +\index[general]{Permissions!Manually resetting the} + +The following solution was provided by Dan Langille \lt{}dan at langille in +the dot org domain\gt{}. The steps are performed using Windows 2000 Server but +they should apply to most Win32 platforms. The procedure outlines how to deal +with a problem which arises when a restore creates a top-level new directory. +In this example, "top-level" means something like {\bf +c:\textbackslash{}src}, not {\bf c:\textbackslash{}tmp\textbackslash{}src} +where {\bf c:\textbackslash{}tmp} already exists. If a restore job specifies / +as the {\bf Where:} value, this problem will arise. + +The problem appears as a directory which cannot be browsed with Windows +Explorer. The symptoms include the following message when you try to click on +that directory: + +\includegraphics{./access-is-denied.eps} + +If you encounter this message, the following steps will change the permissions +to allow full access. + +\begin{enumerate} +\item right click on the top level directory (in this example, {\bf c:/src}) + and select {\bf Properties}. +\item click on the Security tab. +\item If the following message appears, you can ignore it, and click on {\bf + OK}. + +\includegraphics{./view-only.eps} + +You should see something like this: + +\includegraphics{./properties-security.eps} +\item click on Advanced +\item click on the Owner tab +\item Change the owner to something other than the current owner (which is + {\bf SYSTEM} in this example as shown below). + +\includegraphics{./properties-security-advanced-owner.eps} +\item ensure the "Replace owner on subcontainers and objects" box is + checked +\item click on OK +\item When the message "You do not have permission to read the contents of + directory c:\textbackslash{}src\textbackslash{}basis. Do you wish to replace + the directory permissions with permissions granting you Full Control?", click +on Yes. + +\includegraphics{./confirm.eps} +\item Click on OK to close the Properties tab + \end{enumerate} + +With the above procedure, you should now have full control over your restored +directory. + +In addition to the above methods of changing permissions, there is a Microsoft +program named {\bf cacls} that can perform similar functions. + +\section{Backing Up the WinNT/XP/2K System State} +\index[general]{State!Backing Up the WinNT/XP/2K System} +\index[general]{Backing Up the WinNT/XP/2K System State} + +A suggestion by Damian Coutts using Microsoft's NTBackup utility in +conjunction with Bacula should permit a full restore of any damaged system +files on Win2K/XP. His suggestion is to do an NTBackup of the critical system +state prior to running a Bacula backup with the following command: + +\footnotesize +\begin{verbatim} +ntbackup backup systemstate /F c:\systemstate.bkf +\end{verbatim} +\normalsize + +The {\bf backup} is the command, the {\bf systemstate} says to backup only the +system state and not all the user files, and the {\bf /F +c:\textbackslash{}systemstate.bkf} specifies where to write the state file. +this file must then be saved and restored by Bacula. + +To restore the system state, you first reload a base operating system if the +OS is damaged, otherwise, this is not necessary, then you would use Bacula to +restore all the damaged or lost user's files and to recover the {\bf +c:\textbackslash{}systemstate.bkf} file. Finally if there are any damaged or +missing system files or registry problems, you run {\bf NTBackup} and {\bf +catalogue} the system statefile, and then select it for restore. The +documentation says you can't run a command line restore of the systemstate. + +To the best of my knowledge, this has not yet been tested. If you test it, +please report your results to the Bacula email list. + +\section{Considerations for Filename Specifications} +\index[general]{Windows!Considerations for Filename Specifications} + +Please see the +\ilink{Director's Configuration chapter}{win32} of this manual +for important considerations on how to specify Windows paths in Bacula FileSet +Include and Exclude directives. + +\index[general]{Unicode} +Bacula versions prior to 1.37.28 do not support Windows Unicode filenames. +As of that version, both {\bf bconsole} and {\bf bwx-console} support Windows +Unicode filenames. There may still be some problems with multiple byte +characters (e.g. Chinese, ...) where it is a two byte character but the +displayed character is not two characters wide. + +\index[general]{Win32 Path Length Restriction} +Path/filenames longer than 260 characters (up to 32,000) are supported +beginning with Bacula version 1.39.20. Older Bacula versions support +only 260 character path/filenames. + +\section{Win32 Specific File daemon Command Line} +\index[general]{Client!Win32 Specific File daemon Command Line Options} +\index[general]{Win32 Specific File daemon Command Line Options} + +These options are not normally seen or used by the user, and are documented +here only for information purposes. At the current time, to change the default +options, you must either manually run {\bf Bacula} or you must manually edit +the system registry and modify the appropriate entries. + +In order to avoid option clashes between the options necessary for {\bf +Bacula} to run on Windows and the standard Bacula options, all Windows +specific options are signaled with a forward slash character (/), while as +usual, the standard Bacula options are signaled with a minus (-), or a minus +minus (\verb:--:). All the standard Bacula options can be used on the Windows +version. In addition, the following Windows only options are implemented: + +\begin{description} + +\item [/service ] + \index[fd]{/service} + Start Bacula as a service + +\item [/run ] + \index[fd]{/run} + Run the Bacula application + +\item [/install ] + \index[fd]{/install} + Install Bacula as a service in the system registry + +\item [/remove ] + \index[fd]{/remove} + Uninstall Bacula from the system registry + +\item [/about ] + \index[fd]{/about} + Show the Bacula about dialogue box + +\item [/status ] + \index[fd]{/status} + Show the Bacula status dialogue box + +\item [/events ] + \index[fd]{/events} + Show the Bacula events dialogue box (not yet implemented) + +\item [/kill ] + \index[fd]{/kill} + Stop any running {\bf Bacula} + +\item [/help ] + \index[fd]{/help} + Show the Bacula help dialogue box +\end{description} + +It is important to note that under normal circumstances the user should never +need to use these options as they are normally handled by the system +automatically once Bacula is installed. However, you may note these options in +some of the .bat files that have been created for your use. + +\section{Shutting down Windows Systems} +\index[general]{Shutting down Windows Systems} +\index[general]{Systems!Shutting down Windows} + +Some users like to shutdown their Windows machines after a backup using a +Client Run After Job directive. If you want to do something similar, you might +take the shutdown program from the +\elink{apcupsd project}{\url{http://www.apcupsd.com}} or one from the +\elink{Sysinternals project} +{\url{http://www.sysinternals.com/ntw2k/freeware/psshutdown.shtml}}. diff --git a/docs/manuals/fr/console/Makefile b/docs/manuals/fr/console/Makefile new file mode 100644 index 00000000..9af2083b --- /dev/null +++ b/docs/manuals/fr/console/Makefile @@ -0,0 +1,135 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=console + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Console and Operators Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Consol*.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/console/Makefile.in b/docs/manuals/fr/console/Makefile.in new file mode 100644 index 00000000..9af2083b --- /dev/null +++ b/docs/manuals/fr/console/Makefile.in @@ -0,0 +1,135 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=console + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Console and Operators Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Consol*.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/console/bconsole.tex b/docs/manuals/fr/console/bconsole.tex new file mode 100644 index 00000000..f46853e6 --- /dev/null +++ b/docs/manuals/fr/console/bconsole.tex @@ -0,0 +1,1568 @@ +%% +%% + +\chapter{La console Bacula} +\label{_ConsoleChapter} +\index[general]{Console!Bacula} +\index[general]{La console Bacula} +\index[general]{Console!Bacula} +\index[general]{LA console Bacula} +\addcontentsline{toc}{section}{La console Bacula} + +\section{G\'en\'eralit\'es} +\index[general]{G\'en\'eralit\'es} +\addcontentsline{toc}{section}{G\'en\'eralit\'es} + +La {\bf console Bacula} (parfois d\'esign\'ee "Agent utilisateur") est un programme +qui permet \`a l'utilisateur autoris\'e ou \`a l'administrateur syst\`eme d'interagir +avec le Director. + +Actuellement, la console Bacula existe en deux versions : une interface shell +(fa\c{c}on TTY), et une interface graphique GNOME. Avec la console Bacula, vous +pouvez d\'eterminer l'\'etat d'un job particulier, examiner le contenu du +catalogue et effectuer certaines manipulations de cartouches. + +Il existe d'autre part un programme nomm\'e bwx-console, b\^atie avec wxWidgets qui +offre une interface graphique aux op\'erations de restauration. + +Etant donn\'e que la Console interagit avec le Director au travers du r\'eseau, +il n'est pas n\'ecessaire que les deux programmes r\'esident sur la m\^eme machine. + +Bacula a besoin d'un minimum de retour de la Console afin de pouvoir utiliser plus +d'une cartouche. En effet, lorsqu'il en r\'eclame une nouvelle, il attend jusqu'\`a +ce qu'un op\'erateur lui indique, via la Console, qu'une nouvelle cartouche est mont\'ee. + +\section{Configuration de la Console} +\index[general]{Configuration de la Console} +\index[general]{Configuration!Console} +\index[general]{Configuration de la Console} +\index[general]{Configuration!Console} +\addcontentsline{toc}{section}{Configuration de la Console} + +Lors de son lancement, la Console lit le fichier de configuration standard +nomm\'e {\bf bconsole.conf} (ou {\bf gnome-console.conf} dans le cas de la version +GNOME) Ce fichier d\'efinit une configuration par d\'efaut de la Console et, \`a l'heure +actuelle, la seule ressource d\'efinie est la ressource Director, qui informe +la Console du nom et de l'adresse du Director. Pour plus d'informations sur la +configuration de la Console, voyez le chapitre \ilink{Configurer la Console}{_ChapterStart36} +de ce manuel. + +\section{Utiliser la Console} +\index[general]{Utiliser la Console} +\index[general]{Console!Utiliser la} +\index[general]{Utiliser la Console} +\index[general]{Console!Utiliser la} +\addcontentsline{toc}{section}{Utiliser la Console} + +Le programme Console admet les options suivantes : +\footnotesize +\begin{verbatim} +Usage: bconsole [-s] [-c config_file] [-d debug_level] + -c set configuration file to file + -dnn set debug level to nn + -n no conio + -s no signals + -t test - read configuration and exit + -? print this message. +\end{verbatim} +\normalsize + +Apr\`es son d\'emarrage, la Console est en attente de vos commandes, ce qui +est indiqu\'e par une ast\'erisque (*) (ce n'est pas le cas dans la version +GNOME o\`u vous saisissez vos commandes dans la boite texte en bas de l'\'ecran). +Vous pouvez, pour toutes les commandes, vous contenter d'entrer le nom de la +commande, la Console se chargera de vous demander les arguments n\'ecessaires, +mais dans la plupart des cas, vous pouvez entrer les commandes suivies de leurs +arguments. Le format g\'en\'eral est : + +\footnotesize +\begin{verbatim} + [=] [=] ... +\end{verbatim} +\normalsize + +O\`u {\bf command} est l'une des commandes \'enum\'er\'ees ci-dessous, {\bf keyword} +est l'un des mots-clef \'enum\'er\'es ci-dessous (usuellement suivi d'un argument), +et {\bf argument} est la valeur du mot-clef. La commande peut \^etre abr\'eg\'ee +jusqu'\`a sa plus courte abr\'eviation unique. Si deux commandes commencent +par les m\^emes lettres, c'est celle qui appara\^it en t\^ete dans la liste fournie +par la commande {\bf help} qui sera s\'electionn\'ee si votre abr\'eviation est +ambig\"ue. Aucun des mots-clef suivant la commande ne peut \^etre abr\'eg\'e. + +Par exemple : + +\footnotesize +\begin{verbatim} +list files jobid=23 +\end{verbatim} +\normalsize + +\'enum\`ere les fichiers sauvegard\'es par le job de JobId 23. + +Cette autre commande : + +\footnotesize +\begin{verbatim} +show pools +\end{verbatim} +\normalsize + +affiche toutes les ressources Pool. + +\section{Quitter la Console} +\index[general]{Console!Quitter} +\index[general]{Quitter la Console} +\index[general]{Console!Quitter} +\index[general]{Quitter la Console} +\addcontentsline{toc}{section}{Quitter la Console} + +Normalement, le programme Console se termine si vous saisissez {\bf quit} +ou {\bf exit}. Cependant, il il attend jusq"\`a ce que le Director ait pris +en compte la commande, ce qui peut prendre du temps si ce dernier est d\'ej\`a +occup\'e \`a une t\^ache longue (par exemple, un \'elagage du catalogue). Si vous voulez +quitter la Console imm\'ediatement, utilisez la commande {\bf .quit}. + +Il n'existe actuellement aucun moyen d'interrompre une commande de la Console +une fois lanc\'ee (Ctrl-C ne marche pas). En revanche, \`a l'invite d'une commande +vous demandant de choisir parmi plusieurs possibilit\'es, vous pouvez annuler +la commande en entrant un point ({\bf .}), vous serez dans la plupart des cas +ramen\'e \`a l'invite principal, ou \`a l'invite pr\'ec\'edente, dans le cas de choix +imbriqu\'es. En quelques endroits, comme celui o\`u l'on vous demande un +nom de volume, le point sera pris pour la r\'eponse (Bacula pensera que vous +voulez nommer votre volume "."). Dans cette situation, vous serez la plupart +du temps en mesure d'annuler \`a l'invite suivante. + +\label{keywords} +\section{Index des mots-clef de la Console} +\index[general]{Mots-clef!Index Console} +\index[general]{Index des mots-clef de la Console} +\index[general]{Mots-clef!Index Console} +\index[general]{Index des mots-clef de la Console} +\addcontentsline{toc}{section}{Index des mots-clef de la Console} +Sauf sp\'ecification contraire, chacun des mots-clef suivant admet un argument, +qui est sp\'ecifi\'e apr\`es le mot-clef suivi du signe \'egale. Par exemple : + +\begin{verbatim} +jobid=536 +\end{verbatim} + +Notez que cette liste est probablement incompl\`ete, car le processus de cr\'eation +est toujours en cours. Il se peut aussi qu'elle ne soit pas dans l'ordre +alphab\'etique. + +\begin{description} +\item [restart] + Permis dans la commande {\it python}, provoque le red\'emarrage de + l'interpr\'eteur Python. Ne prend pas d'arguments. +\item [all] + Permis dans les commandes {\it status} et {\it show} pour sp\'ecifier, respectivement, tous les + composants ou toutes les ressources. +\item [before] + Utilis\'e dans la commande {\it restore}. +\item [bootstrap] + Utilis\'e dans la commande {\it restore}. +\item [catalog] + Permis dans la commande {\it use} pour sp\'ecifier le nom de catalogue \`a utiliser. +\item [catalogs] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments +\item [client | fd] +\item [clients] + Utilis\'e dans les commandes {\it show}, {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [counters] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [current] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\item [days] + Utilisé pour définir le nombre de jours que la commande "list nextvol" doit + prendre en compte dans son évaluation des prochains jobs à exécuter. + Le mot-clef "day" peut aussi être utilisé avec la commande "status dir" + afin qu'elle affiche les jobs planifiés pour la période spécifiés. +\item [devices] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [dir | director] +\item [directors] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [directory] + Utilis\'e dans la commande {\it restore}. Son argument spécifie + le répertoire à restaurer. +\item [enabled] + Ce mot-clef peut être utilisé avec la commande {\bf update volume} et admet + l'un des arguments suivants : yes, true, no, false, archived, 0, 1, 2, où + 0 correspond à "no" ou "false", 1 à "yes" ou "true" et 2 à "archived". Les volumes + avec le statut "archived" ne seront pas utilisés, pas plus que ne seront élagués leurs + enregistrements dans le catalogue. Les volumes qui n'ont pas le statut "enabled" + ne seront pas utilisés pour des sauvegardes ou des restaurations. +\item [done] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\item [file] + Utilis\'e dans la commande {\it restore}. +\item [files] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [fileset] +\item [filesets] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [help] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [jobs] + Utilis\'e dans les commandes {\it show}, {\it list} et {\it llist}. Ne prend pas d'arguments. +\item [jobmedia] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [jobtotals] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [jobid] + Le JobId est le num\'ero de job qui est affich\'e dans le rapport de job. + C'est l'index du catalogue pour le job donn\'e. Bien qu'il soit unique + pour tous les jobs existant dans le catalogue, le m\^eme JobId peut + \^etre r\'eutilis\'e une fois qu'un job a \'et\'e supprim\'e du catalogue. + Vous d\'esignerez certainement les jobs sp\'ecifiques par leur JobId. +\item [job | jobname] + Le mot-clef Job ou Jobname se r\'ef\`ere au nom que vous avez sp\'ecifi\'e + dans la ressource Job, et donc peut d\'esigner plusieurs jobs effectu\'es. + C'est particuli\`erement utile lorsque vous voulez la liste des jobs + execut\'es portant un nom particulier. +\item [level] +\item [listing] + Permis dans la commande {\it estimate}. Ne prend pas d'arguments. +\item [limit] +\item [messages] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [media] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [nextvol | nextvolume] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [on] + Ne prend pas d'arguments. +\item [off] + Ne prend pas d'arguments. +\item [pool] +\item [pools] + Utilis\'e dans les commandes, {\it show}, {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [select] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\item [storages] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [schedules] + Utilis\'e dans la commande {\it show}. Ne prend pas d'arguments. +\item [sd | store | storage] +\item [ujobid] + L'ujobid est un identificateur unique de job qui est affich\'e dans + le rapport du job. Actuellement, il consiste en le nom du job + (celui de la directive Name de ce job) suffix\'e de la date et de + l'heure d'ex\'ecution du job. Ce mot-clef est utile si vous voulez + identifier compl\`etement l'instance du job ex\'ecut\'e. +\item [volume] +\item [volumes] + Utilis\'e dans les commandes {\it list}, et {\it llist}. ne prend pas d'arguments. +\item [where] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\item [yes] + Utilis\'e dans la commande {\it restore}. Ne prend pas d'arguments. +\end{description} + +\label{list} +\section{Index des commandes de la Console} +\index[general]{Commandes!Index des commandes de la Console} +\index[general]{Index des commandes de la Console} +\index[general]{Commandes!Index des commandes de la Console} +\index[general]{Index des commandes de la Console} +\addcontentsline{toc}{section}{Index des commandes de la Console} + +Les commandes suivantes sont actuellement impl\'ement\'ees : + +\begin{description} +\item [{add [pool=\lt{}pool-name\gt{} storage=\lt{}storage\gt{} + jobid=\lt{}JobId\gt{}]} ] + \index[general]{add} +Cette commande sert \`a ajouter des volumes \`a un pool existant. Les noms des +volumes saisis sont plac\'es dans le catalogue et deviennent ainsi disponibles +pour les sauvegardes. Normalement, on pr\'ef\`er utiliser la commande {\bf label} +qui remplit les m\^emes fonctions en plus d'apposer une \'etiquette logicielle +(label) sur les bandes, par opposition \`a {\bf add} qui se contente de +r\'ef\'erencer le volume dans le catalogue. Ainsi, si vous utilisez {\bf add}, +le volume doit pr\'eexister et \^etre d\'ej\`a \'etiquet\'e. Cette commande peut +cependant \^etre utile si vous voulez ajouter plusieurs cartouches dans un +pool en ne les \'etiquettant que plus tard. Elle peut aussi se r\'ev\'eler utile +si vous importez des cartouches provenant d'un autre site. Consultez le +paragraphe sur la commande {\bf label} pour conna\^itre la liste des +caract\`eres autoris\'es dans un nom de volume. + +\item [autodisplay on/off] + \index[general]{autodisplay on/off} + Cette commande accepte les arguments {\bf on} ou {\bf off} et active ou + d\'esactive l'affichage automatique des messages. La valeur par d\'efaut dans + la Console est {\bf off}, ce qui signifie que les messages en attente + vous sont notifi\'es, mais qu'ils ne sont pas automatiquement affich\'es. + La valeur par d\'efaut pour la console GNOME est {\bf on}, ainsi les + messages sont affich\'es lorqu'ils sont re\c{c}us (habituellement dans les 5 secondes + apr\`es qu'ils aient \'et\'e g\'en\'er\'es). + + Lorsque l'affichage automatique est d\'esactiv\'e, vous devez explicitement + en demander l'affichage avec la commande {\bf messages}. + +\item [automount on/off] + \index[general]{automount on/off} + Cette commande accepte les arguments {\bf on} ou {\bf off} et active ou + d\'esactive le montage automatique de la cartouche apr\`es une commande {\bf label}. + La valeur par d\'efaut est {\bf on}. Si le montage automatique est d\'esactiv\'e, + vous devez explicitement monter la cartouche apr\`es avoir utilis\'e {\bf label} + pour pouvoir \'ecrire dessus. + +\item [{cancel [jobid=\lt{}number\gt{} job=\lt{}job-name\gt{} ujobid=\lt{}unique-jobid\gt{}]}] + \index[general]{cancel jobid} + Cette commande sert \`a supprimer un job et admet les arguments {\bf jobid=nnn} + ou {\bf job=xxx} o\`u nnn est \`a remplacer par le JobId et xxx par le nom de + job. Si vous lancez cette commande sans arguments, la Console vous propose + de choisir parmi les jobs actifs celui \`a supprimer. + + Une fois qu'un job est marqu\'e "A supprimer", il peut se passer quelques instants + (en g\'en\'eral, moins d'une minute) avant qu'il se termine, en fonction des + op\'erations en cours. + +\item [{ create [pool=\lt{}pool-name\gt{}]}] + \index[general]{create pool} + Cette commande sert \`a cr\'eer un enregistrement Pool dans le catalogue + selon les ressources Pool d\'efinis dans le fichier de configuration + du Director. En un sens, cette commande se content de transf\'erer + l'information depuis la ressource Pool dans le fichier de configuration + vers le catalogue. En principe, cete commande est automatiquement + ex\'ecut\'ee au lancement du Director, pourvu que le pool soit r\'ef\'erenc\'e + dans une ressource Job. Si vous utilisez cette commande sur un pool + existant, elle met \`a jour le catalogue en foction des informations de + la ressource Pool. Apr\`es avoir cr\'e\'e un pool, vous uiliserez + probablement la commande {\bf label} pour \'etiqueter un ou plusieurs + volumes et enregistrer leurs noms dans le catalogue. + + Si, au lancement d'un job, Bacula d\'etermine qu'il n'y a pas de pool + enregistr\'e dans le catalogue, mais qu'il existe une ressource Pool pour + le pool appropri\'e, alors il le cr\'e\'e pour vous. Si vous voulez le voir + appara\^itre imm\'ediatement dans le catalogue, utilisez cette commande pour + forcer sa cr\'eation imm\'ediate. + +\item [{ delete [volume=\lt{}vol-name\gt{} pool=\lt{}pool-name\gt{} job + jobid=\lt{}id\gt{}]}] + \index[general]{delete} + Cette commande s'utilise pour supprimer un volume, un pool ou un job + du catalogue, ainsi que tous les enregistrements du catalogue qui leur + sont associ\'es. Cette commande op\`ere exclusivement sur le catalogue + et n'a aucune r\'epercussion sur les donn\'ees \'ecrites sur les cartouches. + Elle peut \^etre dangereuse, et nous vous recommandons fortement de ne + pas l'utiliser si vous ne savez pas exactement ce que vous faites. + + Voici la forme compl\`ete de cette commande : + +\begin{verbatim} +delete pool=\lt{}pool-name\gt{} +\end{verbatim} + + supprime un pool du catalogue. + +\begin{verbatim} +delete volume=\lt{}volume-name\gt{} pool=\lt{}pool-name\gt{} +\end{verbatim} + + supprime du catalogue un volume du pool sp\'ecifi\'e. + +\begin{verbatim} +delete JobId=\lt{}job-id\gt{} JobId=\lt{}job-id2\gt{} ... +\end{verbatim} + + supprime du catalogue le job sp\'ecifi\'e. + +\begin{verbatim} +delete Job JobId=n,m,o-r,t ... +\end{verbatim} + + supprime les job de JobIds m,n,o,p,q,r et t (o\`u m,n,... sont, bien sur, des + nombres). Ainsi, la commande "delete jobid" accepte les listes et les plages + de jobids. + +\item [disable job\lt{}job-name\gt{}] + \index[general]{enable} + Cette commande vous permet de d\'esactiver un job normalement planifi\'e + pour ex\'ecution. Le job peut avoir \'et\'e pr\'ealablement activ\'e par la + directive {\bf Enabled} dans la ressource Job, ou avec la commande + {\bf enable} dans la Console. Au prochain d\'emarrage du Director, ou + si le fichier de configuration est recharg\'e, l'\'etat Enable/Disable sera + r\'etabli \`a celui sp\'ecifi\'e dans la ressource Job (la valeur par d\'efaut + est enabled). + +\item [enable job\lt{}job-name\gt{}] + \index[general]{enable} + Cette commande vous permet de d'activer un job planifi\'e + pour ex\'ecution automatique. Le job peut avoir \'et\'e pr\'ealablement d\'esactiv\'e par la + directive {\bf Disabled} dans la ressource Job, ou avec la commande + {\bf disable} dans la Console. Au prochain d\'emarrage du Director, ou + si le fichier de configuration est recharg\'e, l'\'etat Enable/Disable sera + r\'etabli \`a celui sp\'ecifi\'e dans la ressource Job (la valeur par d\'efaut + est enabled). + +\label{estimate} +\item [estimate] + \index[general]{estimate} + Avec cette commande, vous pouvez vous faire une id\'ee du nombre de fichier + seront sauvegard\'es. Vous pouvez aussi l'utiliser pour \'eprouver les + param\`etres Include de vos FileSets sans passer par une sauvegarde + r\'eelle. Par d\'efaut, l'estimation est faite pour une sauvegarde Full. + Cependant, vous pouvez passer outre ce comportement en sp\'ecifiant + {\bf level=Incremental} ou {\bf level=Differential} sur la ligne de + commande. Un nom de job doit \^etre sp\'ecifi\'e, faute de quoi il vous sera + demand\'e. Optionnellement, vous pouvez sp\'ecifier un client et un + FileSet sur la ligne de commande. Bacula contacte alors le client + et calcule le nombre de fichier et d'octets qui seraient + sauvegard\'es. Notez qu'il s'agit d'une estimation calcul\'ee d'apr\`es + le nombre de blocs dans les fichiers plut\^ot qu'en lisant le nombre + effectif d'octets. Aussi, la taille estim\'ee est g\'en\'eralement plus + importante que celle de la sauvegarde r\'eelle. + + Optionnellement, vous pouvez ajouter le mot-clef {\bf listing}, auquel cas + tous les fichiers \`a sauvegarder seront affich\'es. Notez qu'un tel affichage + peut prendre un certain temps s'il s'agit d'une grosse sauvegarde. + Voici la forme compl\`ete de cette commande : + +\begin{verbatim} +estimate job=\lt{}job-name\gt{} listing client=\lt{}client-name\gt{} + fileset=\lt{}fileset-name\gt{} level=\lt{}level-name\gt{} +\end{verbatim} + + La sp\'ecification du {\bf job} est suffisante, mais vous pouvez aussi + passer outre le client, le FileSet et/ou le niveau en les + sp\'ecifiant sur la ligne de commande. + + Par exemple, vous pourriez faire ceci : + +\footnotesize +\begin{verbatim} + @output /tmp/listing + estimate job=NightlySave listing level=Incremental + @output +\end{verbatim} +\normalsize + +ce qui produirait une liste compl\`ete de tous les fichiers \`a sauvegarder pour +le job {\bf NightlySave} au cours d'une sauvegarde incr\'ementale, et qui +consignerait cette liste dans le fichier {\bf /tmp/listing}. Notez que l'évaluation +produite par cette commande se base sur les tailles de fichiers contenues dans +l'objet "répertoire", aussi l'estimation peut être très éloignée de la réalité si vous +avez des fichiers creux (NDT : sparse files) sur votre système. Ce type de fichiers se +rencontre souvent sur les systèmes 64 bits avec certains systèmes de fichiers. +Le volume obtenu par l'évaluation est celui que sauvegardera Bacula si l'option +sparse est désactivée. Il n'y a actuellement aucun moyen d'évaluer le volume de +ce qui serait sauvegardé avec l'option sparse activée. + +\item [help] + \index[general]{help} + Cette commande affiche la liste des commandes disponibles. + +\item [label] + \index[general]{label} + \index[general]{relabel} + \index[general]{label} + \index[general]{relabel} + Cette commande est utilis\'ee pour \'etiqueter les volumes. La forme compl\`ete est : + +\begin{verbatim} + label storage=\lt{}storage-name\gt{} volume=\lt{}volume-name\gt{} + slot=\lt{}slot\gt{} +\end{verbatim} + + Si vous omettez l'un quelconque des arguments, il vous sera r\'eclam\'e. + Le type de m\'edia est automatiquement r\'ecup\'er\'e de la ressource Storage. + Une fois que les informations requises sont r\'eunies, la Console + contacte le Storage Daemon sp\'ecifi\'e et lui ordonne d'\'etiqueter la + cartouche sp\'ecifi\'ee. Si l'\'etiquetage s'effectue correctement, la + Console cr\'e\'e un nouvel enregistrement dans le catalogue pour le + volume dans le pool appropri\'e. + + Les noms de volumes ne doivent contenir que des lettres, chiffres et + les caract\`eres sp\'eciaux tiret ({\bf -}), sous-lign\'e ({\bf \_}), double-point + ({\bf :}), et point ({\bf .}). Tous les autres caract\`eres, y compris l'espace, + sont ill\'egaux. Cette restriction vise \`a assurer une bonne lisibilit\'e + des noms de volumes pour r\'eduire le risque d'erreurs humaines. + + Notez que lors de l'\'etiquetage d'une cartouche vierge, Bacula obtient des + erreurs {\bf read I/O error} lorqu'il tente de v\'erifier si la cartouche + a d\'ej\`a un label. Si vous voulez \'eviter ce genre de message, placez un + indicateur de fin de fichier sur votre cartouche avant son \'etiquetage : + +\footnotesize +\begin{verbatim} + mt rewind + mt weof + +\end{verbatim} +\normalsize + +La commande label peut \'echouer pour plusieurs raisons : + + +\begin{enumerate} +\item Le nom de volume que vous avez sp\'ecifi\'e figure d\'ej\`a dans le catalogue. +\item Le Storage Daemon a d\'ej\`a une cartouche mont\'ee dans le lecteur. Dans ce cas, + vous devez la d\'emonter ({\bf unmount}) et ins\'erer une cartouche vierge + avant de lancer la commande {\bf label}. +\item La cartouche dans le lecteur porte d\'ej\`a une \'etiquette Bacula. + (Bacula ne r\'e-\'etiquette jamais une cartouche \`a moins qu'elle soit recycl\'ee + et que vous utilisiez la commande {\bf relabel} ). +\item Il n'y a pas de cartouche dans le lecteur. +\end{enumerate} + +Il existe deux moyens pour r\'e-\'etiqueter un volume qui porte d\'ej\`a une +\'etiquette Bacula. La m\'ethode brutale consiste \`a \'ecrire une marque de fin de +fichier sur la cartouche vec la commande du syst\`eme d'exploitation {\bf mt}, +quelque chose dans ce style : + +\footnotesize +\begin{verbatim} + mt -f /dev/st0 rewind + mt -f /dev/st0 weof +\end{verbatim} +\normalsize + +puis d'utiliser la commande {\bf label} pour ajouter une nouvelle \'etiquette. +Cette m\'ethode peut cependant laisser des traces de l'ancien volume dans le +catalogue. + +Il est pr\'ef\'erable d'utiliser la commande {\bf relabel} d\'ecrite ci-dessous sur +un volume purg\'e (automatiquement ou avec la commande {\bf purge}). + +Si votre librairie comporte un lecteur de codes barres, vous pouvez +\'etiqueter tous les volumes qu'elle contient en +utilisant la commande {\bf label barcodes}. En effet, apr\`es le lancement de +cette commande, Bacula monte chaque cartouche l'une apr\`es l'autre et +l'\'etiquette du nom de son code barres. simultan\'ement, l'enregistrement +appropri\'e est cr\'e\'e dans le catalogue. Toute cartouche dont le code barres +commence par les m\^emes caract\`eres que ceux sp\'ecifi\'es par la directive +"CleaningPrefix" de la ressource Pool du director est consid\'er\'ee comme +une cartouche de nettoyage et ne re\c{c}oit donc pas d'\'etiquette, bien +qu'une entr\'ee dans le catalogue lui soit d\'edi\'ee. Par exemple avec : + +\footnotesize +\begin{verbatim} + Pool { + Name ... + Cleaning Prefix = "CLN" + } + +\end{verbatim} +\normalsize + +tout slot contenant une cartouche de code barres CLNxxxxx sera trait\'ee en tant +que cartouche de nettoyage et ne sera jamais mont\'ee. Notez que la forme +compl\`ete de la commande est : + +\footnotesize +\begin{verbatim} +update storage=xxx pool=yyy slots=1-5,10 barcodes +\end{verbatim} +\normalsize + +\item [list] + \index[general]{list} + La commande {\bf list} extrait du catalogue les informations demand\'ees. Les + diff\'erentes champs de chaque enregistrement sont \'enum\'er\'es sur une simple + ligne. Voici les diff\'erentes formes de la commande : + +\footnotesize +\begin{verbatim} + list jobs + + list jobid= (affiche le jobid id) + + list ujobid= (affiche le job dont le nom unique est ) + + list job= (Affiche tous les jobs dont le nom est "job-name") + + list jobname= (voir ci-dessus) + + Dans cette commande, vous pouvez ajouter "limit=nn" pour limiter la sortie \`a nn jobs. + + list jobmedia + + list jobmedia jobid= + + list jobmedia job= + + list files jobid= + + list files job= + + list pools + + list clients + + list jobtotals + + list volumes + + list volumes jobid= + + list volumes pool= + + list volumes job= + + list volume= + + list nextvolume job= + + list nextvol job= + + list nextvol job= days=nnn + + + +\end{verbatim} +\normalsize + + Ce que font la plupart des commandes ci-dessus devrait \^etre plus ou moins \'evident. + En g\'en\'eral, si vous ne sp\'ecifiez pas tous les arguments requis, la Console + vous sollicitera pour les arguments manquants. + + La commande {\bf list nextvol} affiche le nom du volume qui dera utilis\'e par + le job sp\'ecifi\'e. Soyez conscient que le prochain volume utilis\'e + pour un job d\'epend de nombreux facteurs dont le temps, et les autres + jobs qui seront ex\'ecut\'es avant celui sp\'ecifi\'e, qui peuvent remplir une + cartouche qui \'etait vide au moment de l'ex\'ecution de {\bf list nextvol}. + Aussi, consid\'erez la r\'eponse fournie par cette commande comme une bonne + estimation plut\^ot que comme une r\'eponse d\'efinitive. De plus, cette commande + a certains effets de bord : \'etant donn\'e qu'elle ex\'ecute le m\^eme algorithme + qu'un job, elle est susceptible de purger ou recycler un volume. Par d\'efaut, + le job sp\'ecifi\'e doit \^etre ex\'ecut\'e dans les deux jours ou aucun volume + ne sera trouv\'e. Vous pouvez cependant sp\'ecifier jusqu'\`a 50 jours en avant + avec la directive {\bf days=nnn}. Si, par exemple, un vendredi, vous voulez + savoir quel volume sera requis lundi pour le job MyJob, utilisez + {\bf list nextvol job=MyJob days=3}. + + Si vous souhaitez ajouter vos propres commandes pour interroger le + catalogue, vous pouvez les placer dans le fichier {\bf query.sql}. + Cela demande quelques connaissances du langage SQL. Voyez le + paragraphe sur la commande {\bf query} ci-dessous pour plus + d'informations. Voyez aussi le paragraphe sur la commande + {\bf llist} qui permet l'affichage complet des informations du + catalogue. + + Voici un exemple d'affichage produit par la commande {\bf list pools} : + +\footnotesize +\begin{verbatim} ++------+---------+---------+---------+----------+-------------+ +| PoId | Name | NumVols | MaxVols | PoolType | LabelFormat | ++------+---------+---------+---------+----------+-------------+ +| 1 | Default | 0 | 0 | Backup | * | +| 2 | Recycle | 0 | 8 | Backup | File | ++------+---------+---------+---------+----------+-------------+ +\end{verbatim} +\normalsize + + Comme mentionn\'e pr\'ec\'edemment, la commande {\bf list} affiche des + informations du catalogue. Certais \'el\'ements sont ajout\'es dans le catalogue + d\`es le d\'emarrage de Bacula, mais en g\'en\'eral, la plupart ne le sont que + lorsqu'ils sont utilis\'es pour la premi\`ere fois. C'est le cas des clients, + des jobs, etc. + + Bacula cr\'e\'e une entr\'ee relative \`a un nouveau client dans le catalogue + la premi\`ere fois que vous ex\'ecut\'ez un job pour ce client. L'entr\'ee est + cr\'e\'ee que le job aboutisse ou qu'il \'echoue, mais il doit au moins d\'emarrer. + Lorsque le client est contact\'e, des informations suppl\'ementaires sont + r\'ecup\'er\'ees du client (le r\'esultat d'un "uname -a") et ajout\'ees au + catalogue. Un {\bf status} n'entra\^ine pas l'enregistrement dans le catalogue. + + Si vous voulez visualiser les ressources Client disponibles dans votre + catalogue, utilisez la commande {\bf show clients}. + +\item [llist] + \index[general]{llist} + La commande {\bf llist} (pour "long list") admet les m\^emes arguments que la + commande list d\'ecrite ci-dessus. La diff\'erence est que {\bf llist} affiche + le contenu complet de chaque enregistrement du catalogue s\'electionn\'e. + L'affichage des diff\'erents champs est produit verticalement, un champ par + ligne. Cette commande peut \^etre tr\`es prolixe. + + Si, au lieu du {\bf list pools} de l'exemple pr\'ec\'edent, vous saisissez + {\bf llist pools}, vous obtiendrez un affichage de ce genre : + +\footnotesize +\begin{verbatim} + PoolId: 1 + Name: Default + NumVols: 0 + MaxVols: 0 + UseOnce: 0 + UseCatalog: 1 + AcceptAnyVolume: 1 + VolRetention: 1,296,000 + VolUseDuration: 86,400 + MaxVolJobs: 0 + MaxVolBytes: 0 + AutoPrune: 0 + Recycle: 1 + PoolType: Backup + LabelFormat: * + + PoolId: 2 + Name: Recycle + NumVols: 0 + MaxVols: 8 + UseOnce: 0 + UseCatalog: 1 + AcceptAnyVolume: 1 + VolRetention: 3,600 + VolUseDuration: 3,600 + MaxVolJobs: 1 + MaxVolBytes: 0 + AutoPrune: 0 + Recycle: 1 + PoolType: Backup + LabelFormat: File + +\end{verbatim} +\normalsize + +\item [messages] + \index[general]{messages} + Cette commande affiche imm\'ediatement tout message de la console en attente. + + +\item [mount] + \index[general]{mount} + + La commande {\bf mount} est utilis\'ee pour obtenir de Bacula qu'il lise + un volume charg\'e dans un lecteur. C'est un moyen d'indiquer \`a Bacula + que vous avez charg\'e une cartouche qu'il doit examiner. Cette commande + n'est utilis\'ee que lorsque Bacula a demand\'e votre intervention pour + charger un lecteur vide, ou lorsque vous avez explicitement d\'emont\'e + un volume avec la commande {\bf unmount} dans la Console, ce qui + provoque la fermeture du lecteur. Si vous avez une librairie, vous ne + ferez pas op\'erer Bacula dessus avec la commande mount. Voici les + diff\'erentes formes de cette commande : + +mount storage=\lt{}storage-name\gt{} + +mount [ jobid=\lt{}id\gt{} | job=\lt{}job-name\gt{} ] + + Si vous avez sp\'ecifi\'e {\bf Automatic Mount = yes} dans la ressource + Device du Storage Daemon, Alors Bacula pourra acc\'eder automatiquement + au volume, \`a moins que vous ne l'ayez explicitement d\'emont\'e ({\bf unmount}) + dans la Console. + +\item[python] + \index[general]{python} + La commande {\bf python} n'admet qu'un argument : {\bf restart}. + + La commande {\bf python} {\bf restart} r\'einitialise l'interpr\'eteur Python + du Director. Ceci peut \^etre tr\`es utile pour effectuer des tests, car une + fois que le Director est lanc\'e, et l'interpr\'eteur Python initialis\'e, + il n'y a pas d'autre moyen de lui faire int\'egrer des modifications + du script de d\'emarrage {\bf DirStartUp.py}. Pour plus de d\'etails sur + l'\'ecriture de scripts Python, consultez le chapitre \ilink{Ecrire des + scripts Python}{_ChapterStart60}. + +\label{ManualPruning} +\item [prune] + \index[general]{prune} + La commande {\bf prune} permet d'\'elaguer en toute s\'ecurit\'e les + enregistrements expir\'es du catalogue pour les jobs et les volumes. + Cette commande n'affecte que le catalogue, et non les donn\'ees + \'ecrites sur les volumes. Dans tous les cas, la commande {\bf prune} + respecte les p\'eriodes de r\'etention des enregistrements sp\'ecifi\'es. + Vous pouvez \'elaguer les jobs expir\'es, ainsi que les jobs et fichiers + d'un volume sp\'ecifi\'e. + +prune files|jobs|volume client=\lt{}client-name\gt{} +volume=\lt{}volume-name\gt{} + + Pour qu'un volume soit \'elagu\'e, son {\bf VolStatus} doit \^etre Full, + Used, ou Append, faute de quoi l'\'elagage sera sans effet. + +\item [purge] + \index[general]{purge} + La commande {\bf purge} efface les enregistrements sp\'ecifi\'es du catalogue + sans \'egards pour les p\'eriodes de r\'etention. {\bf Purge} n'affecte que le + catalogue, et non les donn\'ees \'ecrites sur les volumes. Cette commande + peut se r\'ev\'eler tr\`es dangereuse car vous pouvez parfaitement supprimer + les enregistrements relatifs \`a des sauvegardes valides et r\'ecentes. Aussi, + nous vous recommandons de ne pas l'utiliser \`a moins de savoir exactement + ce que vous faites. Voici les diff\'erentes formes de la commande {\bf purge} : + +purge files jobid=\lt{}jobid\gt{}|job=\lt{}job-name\gt{}|client=\lt{}client-name\gt{} + +purge jobs client=\lt{}client-name\gt{} (of all jobs) + +purge volume|volume=\lt{}vol-name\gt{} (of all jobs) + + + Pour qu'un volume puisse \^etre purg\'e, son {\bf VolStatus} doit \^etre Full, + Used, ou Append, faute de quoi la purge sera sans effet. + +\item [relabel] + \index[general]{relabel} + \index[general]{relabel} + Cette commande sert \`a r\'e-\'etiqueter physiquement un volume. En voici + la forme compl\`ete : + +relabel storage=\lt{}storage-name\gt{} oldvolume=\lt{}old-volume-name\gt{} + volume=\lt{}newvolume-name\gt{} + + Si vous omettez l'un quelconque des arguments, la console vous sollicitera + pour obtenir les informations manquantes. Pour qu'un volume puisse \^etre + r\'e-\'etiquet\'e, il doit figurer dans le catalogue, et avoir le statut + {\bf Purged} ou {\bf Recycle}. Cette situation peut se pr\'esenter + automatiquement par l'application des p\'eriodes de r\'etention, ou vous + pouvez l'obtenir par une {\bf purge} explicite du volume. + + Une fois que le volume a \'et\'e physiquement r\'e-\'etiquet\'e, les donn\'ees + qu'il contenait sont d\'efinitivement et irr\'em\'ediablement perdues. + +\item [release] + \index[general]{release} + Cette commande ordonne au Storage Daemon de rembobiner la cartouche + dans le lecteur, et de relire son \'etiquette \`a la prochaine utilisation + de la cartouche. + +release storage=\lt{}storage-name\gt{} + + Apr\`es cette commande, le lecteur est gard\'e \`a l'\'etat ouvert par Bacula + (sauf si l'option Always Open est d\'esactiv\'ee dans la configuration + du Storage Daemon), et il ne peut donc \^etre utilis\'e par un autre + programme. Toutefois, il est possible, avec certains lecteurs, de + changer la cartouche \`a ce stade. Lors du prochain job, Bacula saura + relire l'\'etiquette de la cartouche pour savoir laquelle est mont\'ee. + Si vous voulez \^etre en mesure d'utiliser le lecteur avec un autre + programme, par exemple {\bf mt}, vous devez uiliser la commande + {\bf unmount} pour que Bacula le lib\`ere compl\`etement. + +\item [reload] + \index[general]{reload} + Lorsqu'il re\c{c}oit la commande {\bf reload}, le Director relit ses fichiers + de configuration et applique les \'eventuelles modifications. Celles-ci + sont prises en compte imm\'ediatement, et donc effectives pour tous les + jobs \`a venir. Notez cependant qu'en ce qui concerne les modifications + apport\'ees aux Schedules, la prise en compte des nouvelles valeur peut + \^etre report\'ee au del\`a de l'ex\'ecution des jobs d\'ej\`a planifi\'es pour + les deux prochaines heures. Ceci est d\^u au planificateur qui pr\'evoit + "pr\'e-planifie" jusqu'\`a deux heures \`a l'avance les jobs \`a ex\'ecuter. + Ainsi, des jobs qui ont d\'ej\`a \'et\'e "pr\'e-planifi\'es" seront ex\'ecut\'es + suivant les valeurs sp\'ecifi\'ees par la ressource Schedule avant sa + modification. Les nouveaux jobs utiliseront les nouvelles valeurs. + A chaque fois que vous utilisez la commande {\bf reload} alors que + des jobs sont en cours d'ex\'ecution, les valeurs de la configuration + pr\'ec\'edente demeurent en vigueur jusqu'\`a ce que les ces jobs se terminent. + Le Director peut ainsi conserver jusqu'\`a 10 jeux de configurations + ant\'erieures avant de refuser une nouvelle commande {\bf reload}. + Une fois que l'un, au moins, des jeux de valeurs ant\'erieur a \'et\'e accept\'e, + il peut \`a nouveau accepter de nouvelles commandes {\bf reload}. + + Bien qu'il soit possible de recharger la configuration du Director + \`a la vol\'ee, alors m\^eme que des jobs sont en cours d'ex\'ecution, il faut + garder \`a l'esprit que c'est une op\'eration complexe, qui n'est pas d\'enu\'ee + d'effets de bords. C'est pourquoi il est recommand\'e, si vous \^etes amen\'e \`a + utiliser la commande {\bf reload}, de red\'emarrer le Director d\`es que vous + en aurez l'opportunit\'e. + +\label{restore_command} +\item [restore] + \index[general]{restore} + La commande {\bf restore} vous permet de s\'electionner un ou plusieurs jobs + (JobIds) \`a restaurer selon plusieurs m\'ethodes. Une fois que les JobIds ont + \'et\'e s\'electionn\'es, les enregistrements de fichiers sont plac\'es dans une + arborescence interne \`a Bacula, et la Console entre dans un mode de + s\'election interactif qui vous permet de naviguer dans cette arborescence + en s\'electionnant individuellement les fichiers ou r\'epertoires \`a restaurer. + Ce mode est assez similaire au mode de s\'election interactif du programme + Unix {\bf restore} standard. + +restore storage=\lt{}storage-name\gt{} client=\lt{}client-name\gt{} + where=\lt{}path\gt{} pool=\lt{}pool-name\gt{} fileset=\lt{}fileset-name\gt{} + select current all done + + O\`u l'option {\bf current}, si elle est sp\'ecifi\'ee, indique \`a la commande + {\bf restore} de s\'electionner automatiquement la sauvegarde la plus + r\'ecente (sinon, vous serez sollicit\'e \`a ce sujet). L'option {\bf all}, + si elle est sp\'ecifi\'ee, indique \`a la commande {\bf restore} de restaurer + tous les fichiers (sinon, vous serez sollicit\'e \`a ce sujet). Pour plus de + d\'etails concernant la commande {\bf restore}, consultez le chapitre + \ilink{Restaurations avec Bacula}{_ChapterStart13}. + +\item [run] + \index[general]{run} + Cette commande vous permet d'ex\'ecuter imm\'ediatement vos jobs. Voici la forme + compl\`ete de cette commande : + +run job=\lt{}job-name\gt{} client=\lt{}client-name\gt{} + fileset=\lt{}FileSet-name\gt{} level=\lt{}level-keyword\gt{} + storage=\lt{}storage-name\gt{} where=\lt{}directory-prefix\gt{} + when=\lt{}universal-time-specification\gt{} yes + + Toute information omise quoique requise fait l'objet d'une liste de s\'election, + et avant le lancement du job, un bilan des param\`etres vous est pr\'esent\'e avec + options d'accord, refus et modification, \`a moins que vous ayez sp\'ecifi\'e + {\bf yes}, auquel cas le job est imm\'ediatement envoy\'e vers le planificateur. + + Sur mon syst\`eme, j'obtiens ce qui suit lorsque je lance la commande run : + +\footnotesize +\begin{verbatim} +A job name must be specified. +The defined Job resources are: + 1: Matou + 2: Polymatou + 3: Rufus + 4: Minimatou + 5: Minou + 6: PmatouVerify + 7: MatouVerify + 8: RufusVerify + 9: Watchdog +Select Job resource (1-9): + +\end{verbatim} +\normalsize + +Si je choisis le num\'ero 5, j'obtiens : + +\footnotesize +\begin{verbatim} +Run Backup job +JobName: Minou +FileSet: Minou Full Set +Level: Incremental +Client: Minou +Storage: DLTDrive +Pool: Default +When: 2003-04-23 17:08:18 +OK to run? (yes/mod/no): + +\end{verbatim} +\normalsize + +Si maintenant j'entre {\bf yes}, le job est ex\'ecut\'e. Si je choisis {\bf mod}, +voici les otpions qui me sont propos\'ees : + +\footnotesize +\begin{verbatim} +Parameters to modify: + 1: Level + 2: Storage + 3: Job + 4: FileSet + 5: Client + 6: When + 7: Pool +Select parameter to modify (1-7): + +\end{verbatim} +\normalsize + +Vous pouvez, si vous le souhaitez, d\'emarrer un job plus tard, en utilisant le +param\`etre {\bf When}. Pour cela, faites le choix {\bf mod}, puis s\'electionnez +{\bf When} (no. 6) et enfin, saisissez l'heure et le jour de lancement +d\'esir\'es au format AAAA-MM-JJ HH:MM:SS. + +\item [setdebug] + \index[general]{setdebug} + \index[general]{setdebug} + \index[general]{debuggage} + \index[general]{debuggage Win32} + \index[general]{Windows!debuggage} + + Cette commande est utilis\'ee pour param\'etrer le niveau de d\'ebuggage de chaque + {\it daemon}. Voici la forme compl\`ete de cette commande. + +setdebug level=nn [trace=0/1 client=\lt{}client-name\gt{} | dir | director | + storage=\lt{}storage-name\gt{} | all] + + Si le param\`etre de tra\c{c}age est actif (trace=1), alors le {\it daemon} est + plac\'e en mode tra\c{c}age, ce qui signifie que toutes les informations de + d\'ebuggage sont envoy\'ees vers le fichier {\bf bacula.trace} dans le + r\'epertoire courant du {\it daemon}. En principe, ce n'est n\'ecessaire + que pour le d\'ebuggage des clients Win32 o\`u les informations ne peuvent + \^etre envoy\'ees vers un terminal ou redirig\'ees vers un fichier. en mode + tra\c{c}age, chaque message de d\'ebuggage est ajout\'e au fichier, que vous devez + supprimer explicitement lorsque vous avez fini. + +\item [show] + \index[general]{show} + \index[general]{show} + LA commande {\bf show} \'enum\`ere les directives des ressources du Director + telles qu'ells sont d\'efinies dans son fichier de configuration. + Cette commande est surtout utilis\'ee par les d\'eveloppeurs \`a des fins + de d\'ebuggage. LEs mots-clef suivants sont accept\'es : + catalogs, clients, counters, devices, directors, + filesets, jobs, messages, pools, schedules, storages, all, help. + Ne confondez pas cette commande ave la commande {\bf list}, qui affiche + quand \`a elle le contenu du catalogue. + +\item [sqlquery] + \index[general]{sqlquery} + La commande {\bf sqlquery} place le programme Console en mode de + requ\^etes SQL, dans lequel chaque ligne que vousq tapez est concat\'en\'ee + \`a la pr\'ec\'edents jusqu'\`a ce qu'un point-virgule (;) soit rencontr\'e. Le + point-virgule termine la commande qui est alors directement envoy\'e au moteur + de base de donn\'ee SQL. Lorsque le r\'esultat issu de la base de donn\'ee SQL est + affich\'e, la Console est pr\`ete \`a recevoir une nouvelle commande SQL. + Pour sortir du mode {\bf sqlquery} et reevenir \`a l'invite de la Console, + entrez un point (.). + + Cette commande vous permet d'interroger directement le catalogue. Notez + que vous devriez savoir exactement ce que vous faites en utilisant cette + commande, car vous pouvez endommager s\'erieusement votre catalogue. + Consultez le paragraphe relatif \`a la commande {\bf query} qui offre un + moyen \`a la fois plus simple et plus sur de saisir des requ\^etes SQL. + + En fonction du moteur de base de donn\'ees que vous utilisez (MySQL, + PostgreSQL ou SQLite), vous disposerez de commandes quelque peu diff\'erentes. + Pour plus de d\'etails, r\'ef\'erez-vous aux documentations de MySQL, PostgreSQL + ou SQLite. + +\item [status] + \index[general]{status} + Cette commande produit un \'etat des prochains jobs planifi\'es au cours des + 24 prochanes heures, ainsi que l'\'etat des jobs en cours d'ex\'ecution. Voici + la forme compl\`ete de cette commande : + +status [all | dir=\lt{}dir-name\gt{} | director | + client=\lt{}client-name\gt{} | storage=\lt{}storage-name\gt{} | + days=nnn] + + Si vous entrez {\bf status dir}, la Console \'enum\`ere tous les jobs en cours + d'ex\'ecution, un r\'esum\'e des jobs planifi\'e pour ex\'ecution au cours des prochaines + 24 heures incluant le volume qui sera probablement utilis\'e, et donne la liste + des dix derniers jobs ex\'ecut\'es avec leurs \'etats. Gardez \`a l'esprit les deux + \'el\'ements suivants : + \begin{itemize} + \item L'obtention du volume n\'ecessite d'appliquer le m\^eme algorithme que + celui utilis\'e lors de l'ex\'ecution d'un job, ce qui peut r\'esulter en un \'elagage + de cartouche. + \item Le volume affich\'e est, au mieux, une bonne supposition. En effet le + volume effectivement utilis\'e peut \^etre diff\'erent en raison du temps \'ecoul\'e + entre le status et l'ex\'ecution du job, un autre job ayant pu, entre temps, + remplir compl\`etement la cartouche. + \end{itemize} + + Dans la liste des jobs en cours d'ex\'ecutions, vous pouvez trouver ce type + d'informations : + +\footnotesize +\begin{verbatim} +2507 Catalog MatouVerify.2004-03-13_05.05.02 is waiting execution +5349 Full CatalogBackup.2004-03-13_01.10.00 is waiting for higher + priority jobs to finish +5348 Differe Minou.2004-03-13_01.05.09 is waiting on max Storage jobs +5343 Full Rufus.2004-03-13_01.05.04 is running +\end{verbatim} +\normalsize + + La liste ci-dessus indique que le job de JobId 5343 (Rufus) est en cours. + Le job de JobId 5348 (Minou) est en attente de la fin du job 5343 + qui utilise la m\^eme ressource Storage, ce qui provoque le "waiting + on max Storage jobs". Le job de JobId 5349 a une priorit\'e inf\'erieure + \`a celle de tous les autres jobs, aussi, il est en attente de la fin de + jobs de priorit\'es sup\'erieures. Finalement, le job de jobId 2508 (MatouVerify) + est en attente ("waiting execution") car un seul job peut \^etre ex\'ecut\'e + en m\^eme temps. + + Si vous faites un {\bf status dir}, Bacula affiche par d\'efaut les premi\`eres + occurrences de tous les jobs pr\'evus pour ex\'ecution aujourd'hui et demain. + Si vous voulez voir les jobs pr\'evus pour les trois prochains jours, + (Si, par exemple vendredi, vous voulez voir les premi\`eres occurrences + des cartouches \`a utiliser vendredi, samedi, dimanche et lundi), vous + pouvez ajouter l'option {\bf days=3}. Notez, {\bf days=0} montre les + premi\`eres occurrences des jobs planifi\'es pour \^etre ex\'ecut\'es aujourd'hui + seulement. Si vous avez plusieurs ex\'ecutions planifi\'ees, pour chaque + job, seule la premi\`ere occurrence sera affich\'e pour la p\'eriode sp\'ecifi\'ee. + + Si votre job para\^it bloqu\'e, vous pouvez avoir une id\'ee g\'en\'erale du probl\`eme + en utilisant {\bf status dir}, et obtenir une information plus sp\'ecifique + avec {\bf status storage=xxx}. Par exemple, si j'utilise cette derni\`ere + commande sur un syst\`eme inoccup\'e, j'obtiens : + +\footnotesize +\begin{verbatim} +status storage=File +Connecting to Storage daemon File at 192.168.68.112:8103 + +rufus-sd Version: 1.39.6 (24 March 2006) i686-pc-linux-gnu redhat (Stentz) +Daemon started 26-Mar-06 11:06, 0 Jobs run since started. + +Running Jobs: +No Jobs running. +==== + +Jobs waiting to reserve a drive: +==== + +Terminated Jobs: + JobId Level Files Bytes Status Finished Name +====================================================================== + 59 Full 234 4,417,599 OK 15-Jan-06 11:54 kernsave +==== + +Device status: +utochanger "DDS-4-changer" with devices: + "DDS-4" (/dev/nst0) +Device "DDS-4" (/dev/nst0) is mounted with Volume="TestVolume002" +Pool="*unknown*" + Slot 2 is loaded in drive 0. + Total Bytes Read=0 Blocks Read=0 Bytes/block=0 + Positioned at File=0 Block=0 +Device "Dummy" is not open or does not exist. +No DEVICE structure. + +Device "DVD-Writer" (/dev/hdc) is not open. +Device "File" (/tmp) is not open. +==== + +In Use Volume status: +==== +\end{verbatim} +\normalsize + +Ce qui r\'ev\`ele qu'aucun job n'est en cours d'ex\'ecution, et qu'aucun des +p\'eriph\'eriques n'est en cours d'utilisation. Si je d\'emonte la librairie +({\bf unmount}), qui ne sera plus utilis\'ee dans cet exemple, et que je lance +un job qui utilise le stockage File, le job se bloque. Si je demande \`a +nouveau {\bf status storage=xxx}, j'obtiens : + +\footnotesize +\begin{verbatim} +status storage=File +... +Device status: +Autochanger "DDS-4-changer" with devices: + "DDS-4" (/dev/nst0) +Device "DDS-4" (/dev/nst0) is not open. + Device is BLOCKED. User unmounted. + Drive 0 is not loaded. +Device "Dummy" is not open or does not exist. +No DEVICE structure. + +Device "DVD-Writer" (/dev/hdc) is not open. +Device "File" (/tmp) is not open. + Device is BLOCKED waiting for media. +==== +... +\end{verbatim} +\normalsize + +Il devrait maintenant \^etre clair que si un job n\'ecessitant la librairie +est ex\'ecut\'e, il bloquera en raison du d\'emontage de cette derni\`ere par +l'utilisateur. Mais le probl\`eme pour le job que j'ai lanc\'e avec le +p\'eriph\'erique "File" est que le p\'eriph\'erique est bloqu\'e en attente +d'un media : Bacula a besoin que vous \'etiquetiez un volume. + +\item [unmount] + \index[general]{unmount} + Cette commande sert \`a ordonner au Storage Daemon de d\'emonter le p\'eriph\'erique + sp\'ecifi\'e. Les formes de cette commande sont les m\^emes que celle de la commande + mount : + +\footnotesize +\begin{verbatim} +unmount storage= + +unmount [ jobid= | job= ] +\end{verbatim} +\normalsize + +\label{UpdateCommand} +\item [update] + \index[general]{update} + Cette commande met \`a jour le catalogue, que ce soit pour un pool sp\'ecifique, + un enregistrement de volume, ou les slots d'une librairie dot\'ee d'un lecteur + de codes barres. Dans le cas de la mise \`a jour d'un enregistrement de pool, + la nouvelle configuration est automatiquement r\'ecup\'er\'ee de la ressource + correspondante du fichier de configuration du Director. Cette commande peut + notamment servir \`a augmenter le nombre maxial de volumes dans un pool. Les + principaux mots-clef suivants peuvent \^etre utilis\'es : + +\footnotesize +\begin{verbatim} + media, volume, pool, slots +\end{verbatim} +\normalsize + +Dans le cas de la mise \`a jour d'un volume, vous serez interrog\'e sur le +param\`etre que vous voulez modifier. Voici ces param\`etres : + +\footnotesize +\begin{verbatim} + + Volume Status + Volume Retention Period + Volume Use Duration + Maximum Volume Jobs + Maximum Volume Files + Maximum Volume Bytes + Recycle Flag + Slot + InChanger Flag + Pool + Volume Files + Volume from Pool + All Volumes from Pool + +\end{verbatim} +\normalsize + + Pour le param\`etre slot, {\bf update slots}, Bacula obtient une liste + de tous les slots et de leurs codes barres du Storage Daemon, + pour chaque code barres trouv\'e, le slot est mis \`a jour dans + l'enregistrement Media du catalogue. C'est tr\`es pratique si vous + d\'eplacez des cartouches dans la librairie, ou si vous changez des + magasins de cartouches. Dans la foul\'ee, le drapeau InChanger est + aussi mis \`a jour.Ceci permet \`a BAcula de savoir quels cartouches sont + effectivement dans la librairie. + + Si vous n'avez pas de lecteur de codes barres, vous pouvez faire la + m\^eme chose depuis la version 1.33 gr\^ace \`a la commande {\bf update slots scan}. + Le mot-clef {\bf scan} ordonne \`a Bacula de monter physiquement chaque + cartouche afin de lire son VolumeName. + + Pour le param\`etre Pool, {\bf update pool}, Bacula d\'eplace le volume de + son pool courant vers le pool sp\'ecifi\'e. + + Pour les parm\`etres {\bf Volume from Pool} et {\bf All Volumes from Pool}, + les valeurs suivantes sont mises \`a jour depuis l'enregistrement + de pool : Recycle, VolRetention, VolUseDuration, MaxVolJobs, MaxVolFiles, + and MaxVolBytes. + + Voici la forme compl\`ete de la commande {\bf update} : + +\footnotesize +\begin{verbatim} + update volume=xxx pool=yyy slots volstatus=xxx VolRetention=ddd + VolUse=ddd MaxVolJobs=nnn MaxVolBytes=nnn Recycle=yes|no + slot=nnn enabled=n + +\end{verbatim} +\normalsize + +\item [use] + \index[general]{use} + Cette commande vous perment de pr\'eciser le catalogue que vous voulez utiliser. + En principe, vous n'utiliserez qu'un seul catalogue, aussi vous n'aurez pas + besoin de faire ce choix. Sinon, utilisez cette commande pour passer de l'un + de vos catalogues \`a l'autre. + +use \lt{}database-name\gt{} + +\item [var] + \label{var} + \index[general]{var name} + Cette commande prend une cha\^ine \'eventuellement encadr\'ee de guillemets et effectue + l'expansion des variables comme elle serait effectu\'ee au niveau de la + directive {\bf LabelFormat}. Ainsi, vous pouvez tester vos cha\^ines + de format d'\'etiquetage. La diff\'erence entre la commande {\bf var} et le + processus effectif est que pour la premi\`ere, aucun job n'est en cours, + aussi des valeurs factices sont utilis\'ees au lieu des variables sp\'ecifiques + aux jobs. Cela vous permet cependant de vous faire une bonne id\'ee de ce qui + se passerait dans le cas r\'eel. + +\item [version] + \index[general]{version} + Cette commande affiche la version du Director. + +\item [quit] + \index[general]{quit} + Cette commande stoppe le programme Console. Celui-ci envoie la requ\^ete + {\bf quit} au Director et attend son accus\'e de r\'eception. Si le Director + est occup\'e, cela peut prendre un certain temps. Vous pouvez quitter + imm\'ediatement en utilisant la variante {\bf .quit} ({\bf quit} pr\'ec\'ed\'ee + d'un point). + +\item [query] + \index[general]{query} + Cette commande lit une requ\^ete SQL pr\'ed\'efinie dans le fichier de requ\^etes + (le nom et l'emplacement de ce fichier sont d\'efinis par la directive + QueryFile du fichier de configuration du Director). Il vous est alors + demand\'e de s\'electionner une requ\^ete du fichier, et \'eventuellement de + saisir un ou plusieurs param\`etres. La requ\^ete est alors soumise au + moteur de base de donn\'ees. + +Les requ\^etes suivantes sont actuellement (version 1.24) disponibles : + +\footnotesize +\begin{verbatim} +Available queries: + 1: List Job totals: + 2: List where a file is saved: + 3: List where the most recent copies of a file are saved: + 4: List total files/bytes by Job: + 5: List total files/bytes by Volume: + 6: List last 20 Full Backups for a Client: + 7: List Volumes used by selected JobId: + 8: List Volumes to Restore All Files: + 9: List where a File is saved: +Choose a query (1-9): + +\end{verbatim} +\normalsize + +\item [exit] + \index[general]{exit} + Cette commande termine le programme Console. + +\item [wait] + \index[general]{wait} + Cette commande place le Director en pause jusqu'\`a ce qu'il n'y ait plus + aucun job en ex\'ecution. Cette commande est utile dans des situation + d'utilisation automatis\'ee par scripts telles que les tests de r\'egression + o\`u vous voulez d\'emarrer un job, et attendre qu'il se termine avant de + poursuivre. Cette commande admet les options suivantes : + +\footnotesize +\begin{verbatim} + wait [jobid=nn] [jobuid=unique id] [job=job name] +\end{verbatim} +\normalsize + +\end{description} + +\label{dotcommands} + +\section{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point} +\index[general]{Commands!sp\'eciales, pr\'ec\'ed\'ees d'un point} +\index[general]{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point} +\addcontentsline{toc}{section}{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un point} + +Voici une liste de commandes pr\'efix\'ees d'un point (.). Elles ont pour vocation +d'\^etre utilis\'ees soit dans des programmes {\it batch}, soit par des interfaces +graphiques. Elles ne sont, en principe, pas utilis\'ees en mode interactif. +Une fois que le d\'eveloppement d'interfaces graphiques aura d\'emarr\'e, cette liste +s'accro\^itra consid\'erablement. + +\footnotesize +\begin{verbatim} +.backups job=xxx list backups for specified job +.defaults client=xxx fileset=yyy list defaults for specified client +.die cause the Director to segment fault (for debugging) +.dir when in tree mode prints the equivalent to the dir command, + but with fields separated by commas rather than spaces. +.jobs list all job names +.levels list all levels +.filesets list all fileset names +.clients list all client names +.pools list all pool names +.types list job types +.msgs return any queued messages +.messages get quick messages +.help help command output +.quit quit +.status get status output +.exit quit +\end{verbatim} +\normalsize + +\label{atcommands} + +\section{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)} +\index[general]{Commandes!sp\'eciales arobase @} +\index[general]{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)} +\addcontentsline{toc}{section}{Commandes sp\'eciales, pr\'ec\'ed\'ees d'un arobase (@)} + +Normalement, toutes les commandes saisies dans la Console sont imm\'ediatement +transmises au Director, qui peut r\'esider sur une autre machine, afin d'y \^etre +ex\'ecut\'ees. Il existe cependant quelques commandes, toutes pr\'ec\'ed\'ees du +caract\`ere arobase (@), qui ne sont pas envoy\'ees au Director, mais +directement interpr\'et\'ees par la Console. Notez que seule la Console +tty impl\'emente ces commandes, et non la Console GNOME. En voici la liste : + +\begin{description} + +\item [@input \lt{}nom-de-fichier\gt{}] + \index[general]{@input \lt{}nom-de-fichier\gt{}} + Lit et ex\'ecute les commandes consign\'ees dans le fichier sp\'ecifi\'e. + +\item [@output \lt{}nom-de-fichier\gt{} w/a] + \index[general]{@output \lt{}nom-de-fichier\gt{} w/a} + Envoit l'ensemble des retours de la Console vers le fichier sp\'ecifi\'e, + avec \'ecrasement si l'option {\bf w} est sp\'ecifi\'ee, ou ajout \`a la suite si l'option + {\bf a} est sp\'ecifi\'ee. Pour rediriger la sortie vers le terminal, entrez + simplement {\bf output} sans sp\'ecifier de nom de fichier. + ATTENTION : prenez garde de ne pas \'ecraser un fichier valide. + Voici un exemple typique lors d'un test de r\'egression : + +\footnotesize +\begin{verbatim} + @output /dev/null + commands ... + @output + +\end{verbatim} +\normalsize + +\item [@tee \lt{}nom-de-fichier\gt{} w/a] + \index[general]{@tee \lt{}nom-de-fichier\gt{} w/a} + Comme la commande pr\'ec\'edente avec envoi simultan\'e vers le terminal. Pour + sortir de ce mode, vous pouvez utiliser {\bf @tee} ou {\bf @output} sans + sp\'ecifier de nom de fichier. + +\item [@sleep \lt{}seconds\gt{}] + \index[general]{@sleep \lt{}seconds\gt{}} + Met en sommeil pour une dur\'ee du nombre de secondes sp\'ecifi\'e. + +\item [@time] + \index[general]{@time} + Affiche la date et l'heure courantes. + +\item [@version] + \index[general]{@version} + Affiche la version de la Console. + +\item [@quit] + \index[general]{@quit} + Quitte. + +\item [@exit] + \index[general]{@exit} + Quitte. + +\item [@\# n-importe-quoi] + \index[general]{n-importe-quoi} + Commentaire. +\end{description} + +\label{scripting} + +\section{Ex\'ecuter la Console depuis un script shell} +\index[general]{Script!Ex\'ecuter la Console depuis un script shell} +\index[general]{Ex\'ecuter la Console depuis un script shell} +\addcontentsline{toc}{section}{Ex\'ecuter la Console depuis un script shell} +Vous pouvez automatiser de nombreuses t\^aches effectu\'ees \`a la Console, en les +ex\'ecutant dans un script shell. Par exemple, si vous avez cr\'e\'e un fichier +contenant ceci : + +\footnotesize +\begin{verbatim} + ./bconsole -c ./bconsole.conf <) { + chomp; + $fileline++; + # If a file is found in an include, process it. + if (($includefile) = /\\include\s*\{(.*?)\}/) { + $includes++; + # Append .tex to the filename + $includefile .= '.tex'; + + # If the include file has already been processed, issue a warning + # and don't do it again. + my $found = 0; + foreach (@$files) { + if ($_ eq $includefile) { + $found = 1; + last; + } + } + if ($found) { + print "$includefile found at line $fileline in $filename was previously included\n"; + } else { + # The file has not been previously found. Save it and + # recursively process it. + push (@$files,$includefile); + get_includes($files,$includefile); + } + } + } + close IF; + } +} + + +sub check_hyphens { + my (@files) = @_; + my ($filedata,$this,$linecnt,$before); + + # Build the test string to check for the various environments. + # We only do the conversion if the multiple hyphens are outside of a + # verbatim environment (either \begin{verbatim}...\end{verbatim} or + # \verb{--}). Capture those environments and pass them to the output + # unchanged. + + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # Set up to process the file data. + $linecnt = 1; + + # Go through the file data from beginning to end. For each match, save what + # came before it and what matched. $filedata now becomes only what came + # after the match. + # Chech the match to see if it starts with a multiple-hyphen. If so + # warn the user. Keep track of line numbers so they can be output + # with the warning message. + while ($filedata =~ /$teststr/os) { + $this = $&; + $before = $`; + $filedata = $'; + $linecnt += $before =~ tr/\n/\n/; + + # Check if the multiple hyphen is present outside of one of the + # acceptable constructs. + if ($this =~ /^\-+/) { + print "Possible unwanted multiple hyphen found in line ", + "$linecnt of file $file\n"; + } + $linecnt += $this =~ tr/\n/\n/; + } + } +} +################################################################## +# MAIN #### +################################################################## + +my (@includes,$cnt); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +get_includes(\@includes,@ARGV); + +check_hyphens(@includes); diff --git a/docs/manuals/fr/console/console.css b/docs/manuals/fr/console/console.css new file mode 100644 index 00000000..d1824aff --- /dev/null +++ b/docs/manuals/fr/console/console.css @@ -0,0 +1,30 @@ +/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ +.MATH { font-family: "Century Schoolbook", serif; } +.MATH I { font-family: "Century Schoolbook", serif; font-style: italic } +.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold } + +/* implement both fixed-size and relative sizes */ +SMALL.XTINY { font-size : xx-small } +SMALL.TINY { font-size : x-small } +SMALL.SCRIPTSIZE { font-size : smaller } +SMALL.FOOTNOTESIZE { font-size : small } +SMALL.SMALL { } +BIG.LARGE { } +BIG.XLARGE { font-size : large } +BIG.XXLARGE { font-size : x-large } +BIG.HUGE { font-size : larger } +BIG.XHUGE { font-size : xx-large } + +/* heading styles */ +H1 { } +H2 { } +H3 { } +H4 { } +H5 { } + +/* mathematics styles */ +DIV.displaymath { } /* math displays */ +TD.eqno { } /* equation-number cells */ + + +/* document-specific styles come next */ diff --git a/docs/manuals/fr/console/console.tex b/docs/manuals/fr/console/console.tex new file mode 100644 index 00000000..69ce36a3 --- /dev/null +++ b/docs/manuals/fr/console/console.tex @@ -0,0 +1,78 @@ +%% +%% +%% The following characters must be preceded by a backslash +%% to be entered as printable characters: +%% +%% # $ % & ~ _ ^ \ { } +%% + +\documentclass[11pt,a4paper]{book} +\usepackage{html} +\usepackage{float} +\usepackage{graphicx} +\usepackage{bacula} +\usepackage{longtable} +\usepackage{makeidx} +\usepackage{index} +\usepackage{setspace} +\usepackage{hyperref} +\usepackage{url} + + +\makeindex +\newindex{general}{idx}{ind}{General Index} + +\sloppy + +\begin{document} +\sloppy + +\newfont{\bighead}{cmr17 at 36pt} +\parskip 10pt +\parindent 0pt + +\title{\includegraphics{./bacula-logo.eps} \\ \bigskip + \Huge{Bacula Console and Operators Guide} + \begin{center} + \large{It comes in the night and sucks + the essence from your computers. } + \end{center} +} + + +\author{Kern Sibbald} +\date{\vspace{1.0in}\today \\ + This manual documents Bacula version \input{version} \\ + \vspace{0.2in} + Copyright \copyright 1999-2007, Free Software Foundation Europe + e.V. \\ + \vspace{0.2in} + Permission is granted to copy, distribute and/or modify this document under the terms of the + GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU Free Documentation License". +} + +\maketitle + +\clearpage +\tableofcontents +\clearpage +\listoffigures +\clearpage +\listoftables +\clearpage + +\include{bconsole} +\include{gui} +\include{fdl} + + +% The following line tells link_resolver.pl to not include these files: +% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main + +% pull in the index +\clearpage +\printindex[general] + +\end{document} diff --git a/docs/manuals/fr/console/do_echo b/docs/manuals/fr/console/do_echo new file mode 100644 index 00000000..04b9f79a --- /dev/null +++ b/docs/manuals/fr/console/do_echo @@ -0,0 +1,6 @@ +# +# Avoid that @VERSION@ and @DATE@ are changed by configure +# This file is sourced by update_version +# +echo "s%@VERSION@%${VERSION}%g" >${out} +echo "s%@DATE@%${DATE}%g" >>${out} diff --git a/docs/manuals/fr/console/fdl.tex b/docs/manuals/fr/console/fdl.tex new file mode 100644 index 00000000..b46cd990 --- /dev/null +++ b/docs/manuals/fr/console/fdl.tex @@ -0,0 +1,485 @@ +% TODO: maybe get rid of centering + +\chapter{GNU Free Documentation License} +\index[general]{GNU Free Documentation License} +\index[general]{License!GNU Free Documentation} + +\label{label_fdl} + + \begin{center} + + Version 1.2, November 2002 + + + Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc. + + \bigskip + + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + \bigskip + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +\end{center} + + +\begin{center} +{\bf\large Preamble} +\end{center} + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +\begin{center} +{\Large\bf 1. APPLICABILITY AND DEFINITIONS} +\end{center} + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The \textbf{"Document"}, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as \textbf{"you"}. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A \textbf{"Modified Version"} of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A \textbf{"Secondary Section"} is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The \textbf{"Cover Texts"} are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A \textbf{"Transparent"} copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called \textbf{"Opaque"}. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The \textbf{"Title Page"} means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as \textbf{"Acknowledgements"}, +\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.) +To \textbf{"Preserve the Title"} +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +\begin{center} +{\Large\bf 2. VERBATIM COPYING} +\end{center} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\begin{center} +{\Large\bf 3. COPYING IN QUANTITY} +\end{center} + + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\begin{center} +{\Large\bf 4. MODIFICATIONS} +\end{center} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} +\item[A.] + Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. + +\item[B.] + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + +\item[C.] + State on the Title page the name of the publisher of the + Modified Version, as the publisher. + +\item[D.] + Preserve all the copyright notices of the Document. + +\item[E.] + Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + +\item[F.] + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + +\item[G.] + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. + +\item[H.] + Include an unaltered copy of this License. + +\item[I.] + Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + +\item[J.] + Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + +\item[K.] + For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + +\item[L.] + Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. + +\item[M.] + Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + +\item[N.] + Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. + +\item[O.] + Preserve any Warranty Disclaimers. +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\begin{center} +{\Large\bf 5. COMBINING DOCUMENTS} +\end{center} + + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + +\begin{center} +{\Large\bf 6. COLLECTIONS OF DOCUMENTS} +\end{center} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +\begin{center} +{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS} +\end{center} + + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +\begin{center} +{\Large\bf 8. TRANSLATION} +\end{center} + + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +\begin{center} +{\Large\bf 9. TERMINATION} +\end{center} + + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\begin{center} +{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE} +\end{center} + + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +\begin{center} +{\Large\bf ADDENDUM: How to use this License for your documents} +% TODO: this is too long for table of contents +\end{center} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\bigskip +\begin{quote} + Copyright \copyright YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +\end{quote} +\bigskip + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + +\bigskip +\begin{quote} + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. +\end{quote} +\bigskip + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +%--------------------------------------------------------------------- diff --git a/docs/manuals/fr/console/fix_tex.pl b/docs/manuals/fr/console/fix_tex.pl new file mode 100755 index 00000000..98657576 --- /dev/null +++ b/docs/manuals/fr/console/fix_tex.pl @@ -0,0 +1,184 @@ +#!/usr/bin/perl -w +# Fixes various things within tex files. + +use strict; + +my %args; + + +sub get_includes { + # Get a list of include files from the top-level tex file. + my (@list,$file); + + foreach my $filename (@_) { + $filename or next; + # Start with the top-level latex file so it gets checked too. + push (@list,$filename); + + # Get a list of all the html files in the directory. + open IF,"<$filename" or die "Cannot open input file $filename"; + while () { + chomp; + push @list,"$1.tex" if (/\\include\{(.*?)\}/); + } + + close IF; + } + return @list; +} + +sub convert_files { + my (@files) = @_; + my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt); + + $cnt = 0; + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # We look for a line that starts with \item, and indent the two next lines (if not blank) + # by three spaces. + my $linecnt = 3; + $indentcnt = 0; + $output = ""; + # Process a line at a time. + foreach (split(/\n/,$filedata)) { + $_ .= "\n"; # Put back the return. + # If this line is less than the third line past the \item command, + # and the line isn't blank and doesn't start with whitespace + # add three spaces to the start of the line. Keep track of the number + # of lines changed. + if ($linecnt < 3 and !/^\\item/) { + if (/^[^\n\s]/) { + $output .= " " . $_; + $indentcnt++; + } else { + $output .= $_; + } + $linecnt++; + } else { + $linecnt = 3; + $output .= $_; + } + /^\\item / and $linecnt = 1; + } + + + # This is an item line. We need to process it too. If inside a \begin{description} environment, convert + # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'. + $itemcnt = 0; + $filedata = $output; + $output = ""; + my ($before,$descrip,$this,$between); + + # Find any \begin{description} environment + while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) { + $output .= $` . $1; + $filedata = $3 . $'; + $descrip = $2; + + # Search for \item {\bf xxx} + while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) { + $descrip = $'; + $output .= $`; + ($between,$descrip) = find_matching_brace($descrip); + if (!$descrip) { + $linecnt = $output =~ tr/\n/\n/; + print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip); + } + + # Now do the replacement. + $between = '{' . $between . '}' if ($between =~ /\[|\]/); + $output .= "\\item \[$between\]"; + $itemcnt++; + } + $output .= $descrip; + } + $output .= $filedata; + + # If any hyphens or \item commnads were converted, save the file. + if ($indentcnt or $itemcnt) { + open OF,">$file" or die "Cannot open output file $file"; + print OF $output; + close OF; + print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n"; + print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n"; + } + + $cnt += $indentcnt + $itemcnt; + } + return $cnt; +} + +sub find_matching_brace { + # Finds text up to the next matching brace. Assumes that the input text doesn't contain + # the opening brace, but we want to find text up to a matching closing one. + # Returns the text between the matching braces, followed by the rest of the text following + # (which does not include the matching brace). + # + my $str = shift; + my ($this,$temp); + my $cnt = 1; + + while ($cnt) { + # Ignore verbatim constructs involving curly braces, or if the character preceding + # the curly brace is a backslash. + if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) { + $this .= $`; + $str = $'; + $temp = $&; + + if ((substr($this,-1,1) eq '\\') or + $temp =~ /^\\verb/) { + $this .= $temp; + next; + } + + $cnt += ($temp eq '{') ? 1 : -1; + # If this isn't the matching curly brace ($cnt > 0), include the brace. + $this .= $temp if ($cnt); + } else { + # No matching curly brace found. + return ($this . $str,''); + } + } + return ($this,$str); +} + +sub check_arguments { + # Checks command-line arguments for ones starting with -- puts them into + # a hash called %args and removes them from @ARGV. + my $args = shift; + my $i; + + for ($i = 0; $i < $#ARGV; $i++) { + $ARGV[$i] =~ /^\-+/ or next; + $ARGV[$i] =~ s/^\-+//; + $args{$ARGV[$i]} = ""; + delete ($ARGV[$i]); + + } +} + +################################################################## +# MAIN #### +################################################################## + +my @includes; +my $cnt; + +check_arguments(\%args); +die "No Files given to Check\n" if ($#ARGV < 0); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +@includes = get_includes(@ARGV); + +$cnt = convert_files(@includes); +print "No lines changed\n" unless $cnt; diff --git a/docs/manuals/fr/console/index.perl b/docs/manuals/fr/console/index.perl new file mode 100644 index 00000000..bc4e1b60 --- /dev/null +++ b/docs/manuals/fr/console/index.perl @@ -0,0 +1,564 @@ +# This module does multiple indices, supporting the style of the LaTex 'index' +# package. + +# Version Information: +# 16-Feb-2005 -- Original Creation. Karl E. Cunningham +# 14-Mar-2005 -- Clarified and Consolodated some of the code. +# Changed to smoothly handle single and multiple indices. + +# Two LaTeX index formats are supported... +# --- SINGLE INDEX --- +# \usepackage{makeidx} +# \makeindex +# \index{entry1} +# \index{entry2} +# \index{entry3} +# ... +# \printindex +# +# --- MULTIPLE INDICES --- +# +# \usepackage{makeidx} +# \usepackage{index} +# \makeindex -- latex2html doesn't care but LaTeX does. +# \newindex{ref1}{ext1}{ext2}{title1} +# \newindex{ref2}{ext1}{ext2}{title2} +# \newindex{ref3}{ext1}{ext2}{title3} +# \index[ref1]{entry1} +# \index[ref1]{entry2} +# \index[ref3]{entry3} +# \index[ref2]{entry4} +# \index{entry5} +# \index[ref3]{entry6} +# ... +# \printindex[ref1] +# \printindex[ref2] +# \printindex[ref3] +# \printindex +# ___________________ +# +# For the multiple-index style, each index is identified by the ref argument to \newindex, \index, +# and \printindex. A default index is allowed, which is indicated by omitting the optional +# argument. The default index does not require a \newindex command. As \index commands +# are encountered, their entries are stored according +# to the ref argument. When the \printindex command is encountered, the stored index +# entries for that argument are retrieved and printed. The title for each index is taken +# from the last argument in the \newindex command. +# While processing \index and \printindex commands, if no argument is given the index entries +# are built into a default index. The title of the default index is simply "Index". +# This makes the difference between single- and multiple-index processing trivial. +# +# Another method can be used by omitting the \printindex command and just using \include to +# pull in index files created by the makeindex program. These files will start with +# \begin{theindex}. This command is used to determine where to print the index. Using this +# approach, the indices will be output in the same order as the newindex commands were +# originally found (see below). Using a combination of \printindex and \include{indexfile} has not +# been tested and may produce undesireable results. +# +# The index data are stored in a hash for later sorting and output. As \printindex +# commands are handled, the order in which they were found in the tex filea is saved, +# associated with the ref argument to \printindex. +# +# We use the original %index hash to store the index data into. We append a \002 followed by the +# name of the index to isolate the entries in different indices from each other. This is necessary +# so that different indices can have entries with the same name. For the default index, the \002 is +# appended without the name. +# +# Since the index order in the output cannot be determined if the \include{indexfile} +# command is used, the order will be assumed from the order in which the \newindex +# commands were originally seen in the TeX files. This order is saved as well as the +# order determined from any printindex{ref} commands. If \printindex commnads are used +# to specify the index output, that order will be used. If the \include{idxfile} command +# is used, the order of the original newindex commands will be used. In this case the +# default index will be printed last since it doesn't have a corresponding \newindex +# command and its order cannot be determined. Mixing \printindex and \include{idxfile} +# commands in the same file is likely to produce less than satisfactory results. +# +# +# The hash containing index data is named %indices. It contains the following data: +#{ +# 'title' => { +# $ref1 => $indextitle , +# $ref2 => $indextitle , +# ... +# }, +# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +#} + + +# Globals to handle multiple indices. +my %indices; + +# This tells the system to use up to 7 words in index entries. +$WORDS_IN_INDEX = 10; + +# KEC 2-18-05 +# Handles the \newindex command. This is called if the \newindex command is +# encountered in the LaTex source. Gets the index ref and title from the arguments. +# Saves the index ref and title. +# Note that we are called once to handle multiple \newindex commands that are +# newline-separated. +sub do_cmd_newindex { + my $data = shift; + # The data is sent to us as fields delimited by their ID #'s. We extract the + # fields. + foreach my $line (split("\n",$data)) { + my @fields = split (/(?:\<\#\d+?\#\>)+/,$line); + + # The index name and title are the second and fourth fields in the data. + if ($line =~ /^ \001 + # @ -> \002 + # | -> \003 + $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines + # protect \001 occurring with images + $str =~ s/\001/\016/g; # 0x1 to 0xF + $str =~ s/\\\\/\011/g; # Double backslash -> 0xB + $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC + $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD + $str =~ s/!/\001/g; # Exclamation point -> 0x1 + $str =~ s/\013/!/g; # 0xD -> Exclaimation point + $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF + $str =~ s/@/\002/g; # At sign -> 0x2 + $str =~ s/\015/@/g; # 0xF to At sign + $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11 + $str =~ s/\|/\003/g; # Vertical line to 0x3 + $str =~ s/\017/|/g; # 0x11 to vertical line + $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is + $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot; + $str =~ s/\011/\\\\/g; # 0x11 to double backslash + local($key_part, $pageref) = split("\003", $str, 2); + + # For any keys of the form: blablabla!blablabla, which want to be split at the + # exclamation point, replace the ! with a comma and a space. We don't do it + # that way for this index. + $key_part =~ s/\001/, /g; + local(@keys) = split("\001", $key_part); + # If TITLE is not yet available use $before. + $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title))); + $TITLE = $before unless $TITLE; + # Save the reference + local($words) = ''; + if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; } + elsif ($SHORT_INDEX) { $words = &make_shortidxname; } + else { $words = &make_idxname; } + local($super_key) = ''; + local($sort_key, $printable_key, $cur_key); + foreach $key (@keys) { + $key =~ s/\016/\001/g; # revert protected \001s + ($sort_key, $printable_key) = split("\002", $key); + # + # RRM: 16 May 1996 + # any \label in the printable-key will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($printable_key =~ /tex2html_anchor_mark/ ) { + $printable_key =~ s/><\/A>$cross_ref_mark/ + $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_label = $external_labels{$label} unless + ($ref_label = $ref_files{$label}); + '"' . "$ref_label#$label" . '">' . + &get_ref_mark($label,$id)} + /geo; + } + $printable_key =~ s/<\#[^\#>]*\#>//go; + #RRM + # recognise \char combinations, for a \backslash + # + $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s + $printable_key =~ s/\&\#;\`
/\\/g; # ditto + $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto + # + # $sort_key .= "@$printable_key" if !($printable_key); # RRM + $sort_key .= "@$printable_key" if !($sort_key); # RRM + $sort_key =~ tr/A-Z/a-z/; + if ($super_key) { + $cur_key = $super_key . "\001" . $sort_key; + $sub_index{$super_key} .= $cur_key . "\004"; + } else { + $cur_key = $sort_key; + } + + # Append the $index_name to the current key with a \002 delimiter. This will + # allow the same index entry to appear in more than one index. + $index_key = $cur_key . "\002$index_name"; + + $index{$index_key} .= ""; + + # + # RRM, 15 June 1996 + # if there is no printable key, but one is known from + # a previous index-entry, then use it. + # + if (!($printable_key) && ($printable_key{$index_key})) + { $printable_key = $printable_key{$index_key}; } +# if (!($printable_key) && ($printable_key{$cur_key})) +# { $printable_key = $printable_key{$cur_key}; } + # + # do not overwrite the printable_key if it contains an anchor + # + if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ )) + { $printable_key{$index_key} = $printable_key || $key; } +# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ )) +# { $printable_key{$cur_key} = $printable_key || $key; } + + $super_key = $cur_key; + } + # + # RRM + # page-ranges, from |( and |) and |see + # + if ($pageref) { + if ($pageref eq "\(" ) { + $pageref = ''; + $next .= " from "; + } elsif ($pageref eq "\)" ) { + $pageref = ''; + local($next) = $index{$index_key}; +# local($next) = $index{$cur_key}; + # $next =~ s/[\|] *$//; + $next =~ s/(\n )?\| $//; + $index{$index_key} = "$next to "; +# $index{$cur_key} = "$next to "; + } + } + + if ($pageref) { + $pageref =~ s/\s*$//g; # remove trailing spaces + if (!$pageref) { $pageref = ' ' } + $pageref =~ s/see/see <\/i> /g; + # + # RRM: 27 Dec 1996 + # check if $pageref corresponds to a style command. + # If so, apply it to the $words. + # + local($tmp) = "do_cmd_$pageref"; + if (defined &$tmp) { + $words = &$tmp("<#0#>$words<#0#>"); + $words =~ s/<\#[^\#]*\#>//go; + $pageref = ''; + } + } + # + # RRM: 25 May 1996 + # any \label in the pageref section will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($pageref) { + if ($pageref =~ /tex2html_anchor_mark/ ) { + $pageref =~ s/><\/A>$cross_ref_mark/ + $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_files{$label} = ''; # ???? RRM + if ($index_labels{$label}) { $ref_label = ''; } + else { $ref_label = $external_labels{$label} + unless ($ref_label = $ref_files{$label}); + } + '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo; + } + $pageref =~ s/<\#[^\#>]*\#>//go; + + if ($pageref eq ' ') { $index{$index_key}='@'; } + else { $index{$index_key} .= $pageref . "\n | "; } + } else { + local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words); + $thisref =~ s/\n//g; + $index{$index_key} .= $thisref."\n | "; + } + #print "\nREF: $sort_key : $index_key :$index{$index_key}"; + + #join('',"$anchor_invisible_mark<\/A>",$_); + + "$anchor_invisible_mark<\/A>"; +} + + +# KEC. -- Copied from makeidx.perl, then modified to do multiple indices. +# Feeds the index entries to the output. This is called for each index to be built. +# +# Generates a list of lookup keys for index entries, from both %printable_keys +# and %index keys. +# Sorts the keys according to index-sorting rules. +# Removes keys with a 0x01 token. (duplicates?) +# Builds a string to go to the index file. +# Adds the index entries to the string if they belong in this index. +# Keeps track of which index is being worked on, so only the proper entries +# are included. +# Places the index just built in to the output at the proper place. +{ my $index_number = 0; +sub add_real_idx { + print "\nDoing the index ... Index Number $index_number\n"; + local($key, @keys, $next, $index, $old_key, $old_html); + my ($idx_ref,$keyref); + # RRM, 15.6.96: index constructed from %printable_key, not %index + @keys = keys %printable_key; + + while (/$idx_mark/) { + # Get the index reference from what follows the $idx_mark and + # remove it from the string. + s/$idxmark\002(.*?)\002/$idxmark/; + $idx_ref = $1; + $index = ''; + # include non- makeidx index-entries + foreach $key (keys %index) { + next if $printable_key{$key}; + $old_key = $key; + if ($key =~ s/###(.*)$//) { + next if $printable_key{$key}; + push (@keys, $key); + $printable_key{$key} = $key; + if ($index{$old_key} =~ /HREF="([^"]*)"/i) { + $old_html = $1; + $old_html =~ /$dd?([^#\Q$dd\E]*)#/; + $old_html = $1; + } else { $old_html = '' } + $index{$key} = $index{$old_key} . $old_html."\n | "; + }; + } + @keys = sort makeidx_keysort @keys; + @keys = grep(!/\001/, @keys); + my $cnt = 0; + foreach $key (@keys) { + my ($keyref) = $key =~ /.*\002(.*)/; + next unless ($idx_ref eq $keyref); # KEC. + $index .= &add_idx_key($key); + $cnt++; + } + print "$cnt Index Entries Added\n"; + $index = '
'.$index unless ($index =~ /^\s*/); + $index_number++; # KEC. + if ($SHORT_INDEX) { + print "(compact version with Legend)"; + local($num) = ( $index =~ s/\ 50 ) { + s/$idx_mark/$preindex
\n$index\n<\/DL>$preindex/o; + } else { + s/$idx_mark/$preindex
\n$index\n<\/DL>/o; + } + } else { + s/$idx_mark/
\n$index\n<\/DL>/o; } + } +} +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# The bibliography and the index should be treated as separate sections +# in their own HTML files. The \bibliography{} command acts as a sectioning command +# that has the desired effect. But when the bibliography is constructed +# manually using the thebibliography environment, or when using the +# theindex environment it is not possible to use the normal sectioning +# mechanism. This subroutine inserts a \bibliography{} or a dummy +# \textohtmlindex command just before the appropriate environments +# to force sectioning. +sub add_bbl_and_idx_dummy_commands { + local($id) = $global{'max_id'}; + + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg; + ## if ($bbl_cnt == 1) { + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo; + #} + $global{'max_id'} = $id; + # KEC. Modified to global substitution to place multiple index tokens. + s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go; + # KEC. Modified to pick up the optional argument to \printindex + s/[\\]printindex\s*(\[.*?\])?/ + do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego; + &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands); +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# For each textohtmlindex mark found, determine the index titles and headers. +# We place the index ref in the header so the proper index can be generated later. +# For the default index, the index ref is blank. +# +# One problem is that this routine is called twice.. Once for processing the +# command as originally seen, and once for processing the command when +# doing the name for the index file. We can detect that by looking at the +# id numbers (or ref) surrounding the \theindex command, and not incrementing +# index_number unless a new id (or ref) is seen. This has the side effect of +# having to unconventionally start the index_number at -1. But it works. +# +# Gets the title from the list of indices. +# If this is the first index, save the title in $first_idx_file. This is what's referenced +# in the navigation buttons. +# Increment the index_number for next time. +# If the indexname command is defined or a newcommand defined for indexname, do it. +# Save the index TITLE in the toc +# Save the first_idx_file into the idxfile. This goes into the nav buttons. +# Build index_labels if needed. +# Create the index headings and put them in the output stream. + +{ my $index_number = 0; # Will be incremented before use. + my $first_idx_file; # Static + my $no_increment = 0; + +sub do_cmd_textohtmlindex { + local($_) = @_; + my ($idxref,$idxnum,$index_name); + + # We get called from make_name with the first argument = "\001noincrement". This is a sign + # to not increment $index_number the next time we are called. We get called twice, once + # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name + # but doesn't use the result so we get called a second time by process_command. This works fine + # except for cases where there are multiple indices except if they aren't named, which is the case + # when the index is inserted by an include command in latex. In these cases we are only able to use + # the index number to decide which index to draw from, and we don't know how to increment that index + # number if we get called a variable number of times for the same index, as is the case between + # making html (one output file) and web (multiple output files) output formats. + if (/\001noincrement/) { + $no_increment = 1; + return; + } + + # Remove (but save) the index reference + s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e; + + # If we have an $idxref, the index name was specified. In this case, we have all the + # information we need to carry on. Otherwise, we need to get the idxref + # from the $index_number and set the name to "Index". + if ($idxref) { + $index_name = $indices{'title'}{$idxref}; + } else { + if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) { + $index_name = $indices{'title'}{$idxref}; + } else { + $idxref = ''; + $index_name = "Index"; + } + } + + $idx_title = "Index"; # The name displayed in the nav bar text. + + # Only set $idxfile if we are at the first index. This will point the + # navigation panel to the first index file rather than the last. + $first_idx_file = $CURRENT_FILE if ($index_number == 0); + $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar. + $toc_sec_title = $index_name; # Index link text in the toc. + $TITLE = $toc_sec_title; # Title for this index, from which its filename is built. + if (%index_labels) { &make_index_labels(); } + if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); } + else { $preindex = ''; } + local $idx_head = $section_headings{'textohtmlindex'}; + local($heading) = join('' + , &make_section_heading($TITLE, $idx_head) + , $idx_mark, "\002", $idxref, "\002" ); + local($pre,$post) = &minimize_open_tags($heading); + $index_number++ unless ($no_increment); + $no_increment = 0; + join('',"
\n" , $pre, $_); +} +} + +# Returns an index key, given the key passed as the first argument. +# Not modified for multiple indices. +sub add_idx_key { + local($key) = @_; + local($index, $next); + if (($index{$key} eq '@' )&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { $index .= "

\n
".&print_key."\n
"; } + else { $index .= "

\n
".&print_key."\n
"; } + } elsif (($index{$key})&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { + $next = "
".&print_key."\n : ". &print_idx_links; + } else { + $next = "
".&print_key."\n
". &print_idx_links; + } + $index .= $next."\n"; + $index_printed{$key} = 1; + } + + if ($sub_index{$key}) { + local($subkey, @subkeys, $subnext, $subindex); + @subkeys = sort(split("\004", $sub_index{$key})); + if ($SHORT_INDEX) { + $index .= "
".&print_key unless $index_printed{$key}; + $index .= "
\n"; + } else { + $index .= "
".&print_key."\n
" unless $index_printed{$key}; + $index .= "
\n"; + } + foreach $subkey (@subkeys) { + $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey}); + } + $index .= "
\n"; + } + return $index; +} + +1; # Must be present as the last line. diff --git a/docs/manuals/fr/console/latex2html-init.pl b/docs/manuals/fr/console/latex2html-init.pl new file mode 100644 index 00000000..14b5c319 --- /dev/null +++ b/docs/manuals/fr/console/latex2html-init.pl @@ -0,0 +1,10 @@ +# This file serves as a place to put initialization code and constants to +# affect the behavior of latex2html for generating the bacula manuals. + +# $LINKPOINT specifies what filename to use to link to when creating +# index.html. Not that this is a hard link. +$LINKPOINT='"$OVERALL_TITLE"'; + + +# The following must be the last line of this file. +1; diff --git a/docs/manuals/fr/console/setup.sm b/docs/manuals/fr/console/setup.sm new file mode 100644 index 00000000..7c88dc61 --- /dev/null +++ b/docs/manuals/fr/console/setup.sm @@ -0,0 +1,23 @@ +/* + * html2latex + */ + +available { + sun4_sunos.4 + sun4_solaris.2 + rs_aix.3 + rs_aix.4 + sgi_irix +} + +description { + From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX +} + +install { + bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex + bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag + bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag + bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag + man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1 +} diff --git a/docs/manuals/fr/console/translate_images.pl b/docs/manuals/fr/console/translate_images.pl new file mode 100755 index 00000000..c7225118 --- /dev/null +++ b/docs/manuals/fr/console/translate_images.pl @@ -0,0 +1,185 @@ +#!/usr/bin/perl -w +# +use strict; + +# Used to change the names of the image files generated by latex2html from imgxx.png +# to meaningful names. Provision is made to go either from or to the meaningful names. +# The meaningful names are obtained from a file called imagename_translations, which +# is generated by extensions to latex2html in the make_image_file subroutine in +# bacula.perl. + +# Opens the file imagename_translations and reads the contents into a hash. +# The hash is creaed with the imgxx.png files as the key if processing TO +# meaningful filenames, and with the meaningful filenames as the key if +# processing FROM meaningful filenames. +# Then opens the html file(s) indicated in the command-line arguments and +# changes all image references according to the translations described in the +# above file. Finally, it renames the image files. +# +# Original creation: 3-27-05 by Karl Cunningham. +# Modified 5-21-05 to go FROM and TO meaningful filenames. +# +my $TRANSFILE = "imagename_translations"; +my $path; + +# Loads the contents of $TRANSFILE file into the hash referenced in the first +# argument. The hash is loaded to translate old to new if $direction is 0, +# otherwise it is loaded to translate new to old. In this context, the +# 'old' filename is the meaningful name, and the 'new' filename is the +# imgxx.png filename. It is assumed that the old image is the one that +# latex2html has used as the source to create the imgxx.png filename. +# The filename extension is taken from the file +sub read_transfile { + my ($trans,$direction) = @_; + + if (!open IN,"<$path$TRANSFILE") { + print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n"; + print " Image filename translation aborted\n\n"; + exit 0; + } + + while () { + chomp; + my ($new,$old) = split(/\001/); + + # Old filenames will usually have a leading ./ which we don't need. + $old =~ s/^\.\///; + + # The filename extension of the old filename must be made to match + # the new filename because it indicates the encoding format of the image. + my ($ext) = $new =~ /(\.[^\.]*)$/; + $old =~ s/\.[^\.]*$/$ext/; + if ($direction == 0) { + $trans->{$new} = $old; + } else { + $trans->{$old} = $new; + } + } + close IN; +} + +# Translates the image names in the file given as the first argument, according to +# the translations in the hash that is given as the second argument. +# The file contents are read in entirely into a string, the string is processed, and +# the file contents are then written. No particular care is taken to ensure that the +# file is not lost if a system failure occurs at an inopportune time. It is assumed +# that the html files being processed here can be recreated on demand. +# +# Links to other files are added to the %filelist for processing. That way, +# all linked files will be processed (assuming they are local). +sub translate_html { + my ($filename,$trans,$filelist) = @_; + my ($contents,$out,$this,$img,$dest); + my $cnt = 0; + + # If the filename is an external link ignore it. And drop any file:// from + # the filename. + $filename =~ /^(http|ftp|mailto)\:/ and return 0; + $filename =~ s/^file\:\/\///; + # Load the contents of the html file. + if (!open IF,"<$path$filename") { + print "WARNING: Cannot open $path$filename for reading\n"; + print " Image Filename Translation aborted\n\n"; + exit 0; + } + + while () { + $contents .= $_; + } + close IF; + + # Now do the translation... + # First, search for an image filename. + while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) { + $contents = $'; + $out .= $` . $&; + + # The next thing is an image name. Get it and translate it. + $contents =~ /^(.*?)\"/s; + $contents = $'; + $this = $&; + $img = $1; + # If the image is in our list of ones to be translated, do it + # and feed the result to the output. + $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img})); + $out .= $this; + } + $out .= $contents; + + # Now send the translated text to the html file, overwriting what's there. + open OF,">$path$filename" or die "Cannot open $path$filename for writing\n"; + print OF $out; + close OF; + + # Now look for any links to other files and add them to the list of files to do. + while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) { + $out = $'; + $dest = $1; + # Drop an # and anything after it. + $dest =~ s/\#.*//; + $filelist->{$dest} = '' if $dest; + } + return $cnt; +} + +# REnames the image files spefified in the %translate hash. +sub rename_images { + my $translate = shift; + my ($response); + + foreach (keys(%$translate)) { + if (! $translate->{$_}) { + print " WARNING: No destination Filename for $_\n"; + } else { + $response = `mv -f $path$_ $path$translate->{$_} 2>&1`; + $response and print "ERROR from system $response\n"; + } + } +} + +################################################# +############# MAIN ############################# +################################################ + +# %filelist starts out with keys from the @ARGV list. As files are processed, +# any links to other files are added to the %filelist. A hash of processed +# files is kept so we don't do any twice. + +# The first argument must be either --to_meaningful_names or --from_meaningful_names + +my (%translate,$search_regex,%filelist,%completed,$thisfile); +my ($cnt,$direction); + +my $arg0 = shift(@ARGV); +$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or + die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n"; + +$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1; + +(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n"; + +# Use the first argument to get the path to the file of translations. +my $tmp = $ARGV[0]; +($path) = $tmp =~ /(.*\/)/; +$path = '' unless $path; + +read_transfile(\%translate,$direction); + +foreach (@ARGV) { + # Strip the path from the filename, and use it later on. + if (s/(.*\/)//) { + $path = $1; + } else { + $path = ''; + } + $filelist{$_} = ''; + + while ($thisfile = (keys(%filelist))[0]) { + $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile})); + delete($filelist{$thisfile}); + $completed{$thisfile} = ''; + } + print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n"; +} + +rename_images(\%translate); diff --git a/docs/manuals/fr/console/update_version b/docs/manuals/fr/console/update_version new file mode 100755 index 00000000..5c2e0092 --- /dev/null +++ b/docs/manuals/fr/console/update_version @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/console/update_version.in b/docs/manuals/fr/console/update_version.in new file mode 100644 index 00000000..2766245f --- /dev/null +++ b/docs/manuals/fr/console/update_version.in @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/console/version.tex b/docs/manuals/fr/console/version.tex new file mode 100644 index 00000000..82d910aa --- /dev/null +++ b/docs/manuals/fr/console/version.tex @@ -0,0 +1 @@ +2.3.6 (04 November 2007) diff --git a/docs/manuals/fr/console/version.tex.in b/docs/manuals/fr/console/version.tex.in new file mode 100644 index 00000000..ff66dfc6 --- /dev/null +++ b/docs/manuals/fr/console/version.tex.in @@ -0,0 +1 @@ +@VERSION@ (@DATE@) diff --git a/docs/manuals/fr/developers/Makefile b/docs/manuals/fr/developers/Makefile new file mode 100644 index 00000000..eb2c5f0f --- /dev/null +++ b/docs/manuals/fr/developers/Makefile @@ -0,0 +1,106 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# + +IMAGES=../../../images + +DOC=developers + +first_rule: all + +all: tex web html dvipdf + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @cp -fp ${IMAGES}/hires/*.eps . + touch ${DOC}.idx ${DOC}i-general.tex + -latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx >/dev/null 2>/dev/null + -latex -interaction=batchmode ${DOC}.tex + @rm -f *.eps *.old + +pdf: + @echo "Making ${DOC} pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + @rm -f *.eps *.old + +dvipdf: + @echo "Making ${DOC} pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + @rm -f *.eps *.old + +html: + @echo "Making ${DOC} html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @touch ${DOC}.html + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + ${DOC} >/dev/null + ./translate_images.pl --to_meaningful_names ${DOC}.html + @rm -f *.eps *.gif *.jpg *.old + +web: + @echo "Making ${DOC} web" + @mkdir -p ${DOC} + @rm -f ${DOC}/* + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @(if [ -f ${DOC}/imagename_translations ] ; then \ + ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html; \ + fi) + @rm -rf ${DOC}/*.html + latex2html -split 4 -local_icons -t "Developer's Guide" -long_titles 4 \ + -contents_in_nav -toc_stars -white -notransparent ${DOC} >/dev/null + ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html + @cp -f ${DOC}/${DOC}_Guide.html ${DOC}/index.html + @rm -f *.eps *.gif *.jpg ${DOC}/*.eps *.old + @rm -f ${DOC}/idle.png + @rm -f ${DOC}/win32-*.png ${DOC}/wx-console*.png ${DOC}/xp-*.png + @rm -f ${DOC}/*.pl ${DOC}/*.log ${DOC}/*.aux ${DOC}/*.idx + @rm -f ${DOC}/*.out WARNINGS + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +clean: + @rm -f 1 2 3 + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.pdf *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f images.pl labels.pl internals.pl + @rm -rf ${DOC} + @rm -f images.tex ${DOC}i.tex + @rm -f ${DOC}i-*.tex + + +distclean: clean + @rm -f ${DOC}.html ${DOC}.pdf + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/developers/Makefile.in b/docs/manuals/fr/developers/Makefile.in new file mode 100644 index 00000000..eb2c5f0f --- /dev/null +++ b/docs/manuals/fr/developers/Makefile.in @@ -0,0 +1,106 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# + +IMAGES=../../../images + +DOC=developers + +first_rule: all + +all: tex web html dvipdf + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @cp -fp ${IMAGES}/hires/*.eps . + touch ${DOC}.idx ${DOC}i-general.tex + -latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx >/dev/null 2>/dev/null + -latex -interaction=batchmode ${DOC}.tex + @rm -f *.eps *.old + +pdf: + @echo "Making ${DOC} pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + @rm -f *.eps *.old + +dvipdf: + @echo "Making ${DOC} pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + @rm -f *.eps *.old + +html: + @echo "Making ${DOC} html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @touch ${DOC}.html + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + ${DOC} >/dev/null + ./translate_images.pl --to_meaningful_names ${DOC}.html + @rm -f *.eps *.gif *.jpg *.old + +web: + @echo "Making ${DOC} web" + @mkdir -p ${DOC} + @rm -f ${DOC}/* + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @(if [ -f ${DOC}/imagename_translations ] ; then \ + ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html; \ + fi) + @rm -rf ${DOC}/*.html + latex2html -split 4 -local_icons -t "Developer's Guide" -long_titles 4 \ + -contents_in_nav -toc_stars -white -notransparent ${DOC} >/dev/null + ./translate_images.pl --to_meaningful_names ${DOC}/Developer*Guide.html + @cp -f ${DOC}/${DOC}_Guide.html ${DOC}/index.html + @rm -f *.eps *.gif *.jpg ${DOC}/*.eps *.old + @rm -f ${DOC}/idle.png + @rm -f ${DOC}/win32-*.png ${DOC}/wx-console*.png ${DOC}/xp-*.png + @rm -f ${DOC}/*.pl ${DOC}/*.log ${DOC}/*.aux ${DOC}/*.idx + @rm -f ${DOC}/*.out WARNINGS + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +clean: + @rm -f 1 2 3 + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.pdf *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f images.pl labels.pl internals.pl + @rm -rf ${DOC} + @rm -f images.tex ${DOC}i.tex + @rm -f ${DOC}i-*.tex + + +distclean: clean + @rm -f ${DOC}.html ${DOC}.pdf + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/developers/catalog.tex b/docs/manuals/fr/developers/catalog.tex new file mode 100644 index 00000000..f67866b5 --- /dev/null +++ b/docs/manuals/fr/developers/catalog.tex @@ -0,0 +1,939 @@ +%% +%% + +\chapter{Catalog Services} +\label{_ChapterStart30} +\index[general]{Services!Catalog } +\index[general]{Catalog Services } + +\section{General} +\index[general]{General } +\addcontentsline{toc}{subsection}{General} + +This chapter is intended to be a technical discussion of the Catalog services +and as such is not targeted at end users but rather at developers and system +administrators that want or need to know more of the working details of {\bf +Bacula}. + +The {\bf Bacula Catalog} services consist of the programs that provide the SQL +database engine for storage and retrieval of all information concerning files +that were backed up and their locations on the storage media. + +We have investigated the possibility of using the following SQL engines for +Bacula: Beagle, mSQL, GNU SQL, PostgreSQL, SQLite, Oracle, and MySQL. Each +presents certain problems with either licensing or maturity. At present, we +have chosen for development purposes to use MySQL, PostgreSQL and SQLite. +MySQL was chosen because it is fast, proven to be reliable, widely used, and +actively being developed. MySQL is released under the GNU GPL license. +PostgreSQL was chosen because it is a full-featured, very mature database, and +because Dan Langille did the Bacula driver for it. PostgreSQL is distributed +under the BSD license. SQLite was chosen because it is small, efficient, and +can be directly embedded in {\bf Bacula} thus requiring much less effort from +the system administrator or person building {\bf Bacula}. In our testing +SQLite has performed very well, and for the functions that we use, it has +never encountered any errors except that it does not appear to handle +databases larger than 2GBytes. That said, we would not recommend it for +serious production use. + +The Bacula SQL code has been written in a manner that will allow it to be +easily modified to support any of the current SQL database systems on the +market (for example: mSQL, iODBC, unixODBC, Solid, OpenLink ODBC, EasySoft +ODBC, InterBase, Oracle8, Oracle7, and DB2). + +If you do not specify either {\bf \verb{--{with-mysql} or {\bf \verb{--{with-postgresql} or +{\bf \verb{--{with-sqlite} on the ./configure line, Bacula will use its minimalist +internal database. This database is kept for build reasons but is no longer +supported. Bacula {\bf requires} one of the three databases (MySQL, +PostgreSQL, or SQLite) to run. + +\subsection{Filenames and Maximum Filename Length} +\index[general]{Filenames and Maximum Filename Length } +\index[general]{Length!Filenames and Maximum Filename } +\addcontentsline{toc}{subsubsection}{Filenames and Maximum Filename Length} + +In general, either MySQL, PostgreSQL or SQLite permit storing arbitrary long +path names and file names in the catalog database. In practice, there still +may be one or two places in the Catalog interface code that restrict the +maximum path length to 512 characters and the maximum file name length to 512 +characters. These restrictions are believed to have been removed. Please note, +these restrictions apply only to the Catalog database and thus to your ability +to list online the files saved during any job. All information received and +stored by the Storage daemon (normally on tape) allows and handles arbitrarily +long path and filenames. + +\subsection{Installing and Configuring MySQL} +\index[general]{MySQL!Installing and Configuring } +\index[general]{Installing and Configuring MySQL } +\addcontentsline{toc}{subsubsection}{Installing and Configuring MySQL} + +For the details of installing and configuring MySQL, please see the +\ilink{Installing and Configuring MySQL}{_ChapterStart} chapter of +this manual. + +\subsection{Installing and Configuring PostgreSQL} +\index[general]{PostgreSQL!Installing and Configuring } +\index[general]{Installing and Configuring PostgreSQL } +\addcontentsline{toc}{subsubsection}{Installing and Configuring PostgreSQL} + +For the details of installing and configuring PostgreSQL, please see the +\ilink{Installing and Configuring PostgreSQL}{_ChapterStart10} +chapter of this manual. + +\subsection{Installing and Configuring SQLite} +\index[general]{Installing and Configuring SQLite } +\index[general]{SQLite!Installing and Configuring } +\addcontentsline{toc}{subsubsection}{Installing and Configuring SQLite} + +For the details of installing and configuring SQLite, please see the +\ilink{Installing and Configuring SQLite}{_ChapterStart33} chapter of +this manual. + +\subsection{Internal Bacula Catalog} +\index[general]{Catalog!Internal Bacula } +\index[general]{Internal Bacula Catalog } +\addcontentsline{toc}{subsubsection}{Internal Bacula Catalog} + +Please see the +\ilink{Internal Bacula Database}{_ChapterStart42} chapter of this +manual for more details. + +\subsection{Database Table Design} +\index[general]{Design!Database Table } +\index[general]{Database Table Design } +\addcontentsline{toc}{subsubsection}{Database Table Design} + +All discussions that follow pertain to the MySQL database. The details for the +PostgreSQL and SQLite databases are essentially identical except for that all +fields in the SQLite database are stored as ASCII text and some of the +database creation statements are a bit different. The details of the internal +Bacula catalog are not discussed here. + +Because the Catalog database may contain very large amounts of data for large +sites, we have made a modest attempt to normalize the data tables to reduce +redundant information. While reducing the size of the database significantly, +it does, unfortunately, add some complications to the structures. + +In simple terms, the Catalog database must contain a record of all Jobs run by +Bacula, and for each Job, it must maintain a list of all files saved, with +their File Attributes (permissions, create date, ...), and the location and +Media on which the file is stored. This is seemingly a simple task, but it +represents a huge amount interlinked data. Note: the list of files and their +attributes is not maintained when using the internal Bacula database. The data +stored in the File records, which allows the user or administrator to obtain a +list of all files backed up during a job, is by far the largest volume of +information put into the Catalog database. + +Although the Catalog database has been designed to handle backup data for +multiple clients, some users may want to maintain multiple databases, one for +each machine to be backed up. This reduces the risk of confusion of accidental +restoring a file to the wrong machine as well as reducing the amount of data +in a single database, thus increasing efficiency and reducing the impact of a +lost or damaged database. + +\section{Sequence of Creation of Records for a Save Job} +\index[general]{Sequence of Creation of Records for a Save Job } +\index[general]{Job!Sequence of Creation of Records for a Save } +\addcontentsline{toc}{subsection}{Sequence of Creation of Records for a Save +Job} + +Start with StartDate, ClientName, Filename, Path, Attributes, MediaName, +MediaCoordinates. (PartNumber, NumParts). In the steps below, ``Create new'' +means to create a new record whether or not it is unique. ``Create unique'' +means each record in the database should be unique. Thus, one must first +search to see if the record exists, and only if not should a new one be +created, otherwise the existing RecordId should be used. + +\begin{enumerate} +\item Create new Job record with StartDate; save JobId +\item Create unique Media record; save MediaId +\item Create unique Client record; save ClientId +\item Create unique Filename record; save FilenameId +\item Create unique Path record; save PathId +\item Create unique Attribute record; save AttributeId + store ClientId, FilenameId, PathId, and Attributes +\item Create new File record + store JobId, AttributeId, MediaCoordinates, etc +\item Repeat steps 4 through 8 for each file +\item Create a JobMedia record; save MediaId +\item Update Job record filling in EndDate and other Job statistics + \end{enumerate} + +\section{Database Tables} +\index[general]{Database Tables } +\index[general]{Tables!Database } +\addcontentsline{toc}{subsection}{Database Tables} + +\addcontentsline{lot}{table}{Filename Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf Filename } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{l| }{\bf Data Type } +& \multicolumn{1}{l| }{\bf Remark } \\ + \hline +{FilenameId } & {integer } & {Primary Key } \\ + \hline +{Name } & {Blob } & {Filename } +\\ \hline + +\end{longtable} + +The {\bf Filename} table shown above contains the name of each file backed up +with the path removed. If different directories or machines contain the same +filename, only one copy will be saved in this table. + +\ + +\addcontentsline{lot}{table}{Path Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf Path } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{PathId } & {integer } & {Primary Key } \\ + \hline +{Path } & {Blob } & {Full Path } +\\ \hline + +\end{longtable} + +The {\bf Path} table contains shown above the path or directory names of all +directories on the system or systems. The filename and any MSDOS disk name are +stripped off. As with the filename, only one copy of each directory name is +kept regardless of how many machines or drives have the same directory. These +path names should be stored in Unix path name format. + +Some simple testing on a Linux file system indicates that separating the +filename and the path may be more complication than is warranted by the space +savings. For example, this system has a total of 89,097 files, 60,467 of which +have unique filenames, and there are 4,374 unique paths. + +Finding all those files and doing two stats() per file takes an average wall +clock time of 1 min 35 seconds on a 400MHz machine running RedHat 6.1 Linux. + +Finding all those files and putting them directly into a MySQL database with +the path and filename defined as TEXT, which is variable length up to 65,535 +characters takes 19 mins 31 seconds and creates a 27.6 MByte database. + +Doing the same thing, but inserting them into Blob fields with the filename +indexed on the first 30 characters and the path name indexed on the 255 (max) +characters takes 5 mins 18 seconds and creates a 5.24 MB database. Rerunning +the job (with the database already created) takes about 2 mins 50 seconds. + +Running the same as the last one (Path and Filename Blob), but Filename +indexed on the first 30 characters and the Path on the first 50 characters +(linear search done there after) takes 5 mins on the average and creates a 3.4 +MB database. Rerunning with the data already in the DB takes 3 mins 35 +seconds. + +Finally, saving only the full path name rather than splitting the path and the +file, and indexing it on the first 50 characters takes 6 mins 43 seconds and +creates a 7.35 MB database. + +\ + +\addcontentsline{lot}{table}{File Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf File } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{FileId } & {integer } & {Primary Key } \\ + \hline +{FileIndex } & {integer } & {The sequential file number in the Job } \\ + \hline +{JobId } & {integer } & {Link to Job Record } \\ + \hline +{PathId } & {integer } & {Link to Path Record } \\ + \hline +{FilenameId } & {integer } & {Link to Filename Record } \\ + \hline +{MarkId } & {integer } & {Used to mark files during Verify Jobs } \\ + \hline +{LStat } & {tinyblob } & {File attributes in base64 encoding } \\ + \hline +{MD5 } & {tinyblob } & {MD5 signature in base64 encoding } +\\ \hline + +\end{longtable} + +The {\bf File} table shown above contains one entry for each file backed up by +Bacula. Thus a file that is backed up multiple times (as is normal) will have +multiple entries in the File table. This will probably be the table with the +most number of records. Consequently, it is essential to keep the size of this +record to an absolute minimum. At the same time, this table must contain all +the information (or pointers to the information) about the file and where it +is backed up. Since a file may be backed up many times without having changed, +the path and filename are stored in separate tables. + +This table contains by far the largest amount of information in the Catalog +database, both from the stand point of number of records, and the stand point +of total database size. As a consequence, the user must take care to +periodically reduce the number of File records using the {\bf retention} +command in the Console program. + +\ + +\addcontentsline{lot}{table}{Job Table Layout} +\begin{longtable}{|l|l|p{2.5in}|} + \hline +\multicolumn{3}{|l| }{\bf Job } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{JobId } & {integer } & {Primary Key } \\ + \hline +{Job } & {tinyblob } & {Unique Job Name } \\ + \hline +{Name } & {tinyblob } & {Job Name } \\ + \hline +{PurgedFiles } & {tinyint } & {Used by Bacula for purging/retention periods +} \\ + \hline +{Type } & {binary(1) } & {Job Type: Backup, Copy, Clone, Archive, Migration +} \\ + \hline +{Level } & {binary(1) } & {Job Level } \\ + \hline +{ClientId } & {integer } & {Client index } \\ + \hline +{JobStatus } & {binary(1) } & {Job Termination Status } \\ + \hline +{SchedTime } & {datetime } & {Time/date when Job scheduled } \\ + \hline +{StartTime } & {datetime } & {Time/date when Job started } \\ + \hline +{EndTime } & {datetime } & {Time/date when Job ended } \\ + \hline +{JobTDate } & {bigint } & {Start day in Unix format but 64 bits; used for +Retention period. } \\ + \hline +{VolSessionId } & {integer } & {Unique Volume Session ID } \\ + \hline +{VolSessionTime } & {integer } & {Unique Volume Session Time } \\ + \hline +{JobFiles } & {integer } & {Number of files saved in Job } \\ + \hline +{JobBytes } & {bigint } & {Number of bytes saved in Job } \\ + \hline +{JobErrors } & {integer } & {Number of errors during Job } \\ + \hline +{JobMissingFiles } & {integer } & {Number of files not saved (not yet used) } +\\ + \hline +{PoolId } & {integer } & {Link to Pool Record } \\ + \hline +{FileSetId } & {integer } & {Link to FileSet Record } \\ + \hline +{PurgedFiles } & {tiny integer } & {Set when all File records purged } \\ + \hline +{HasBase } & {tiny integer } & {Set when Base Job run } +\\ \hline + +\end{longtable} + +The {\bf Job} table contains one record for each Job run by Bacula. Thus +normally, there will be one per day per machine added to the database. Note, +the JobId is used to index Job records in the database, and it often is shown +to the user in the Console program. However, care must be taken with its use +as it is not unique from database to database. For example, the user may have +a database for Client data saved on machine Rufus and another database for +Client data saved on machine Roxie. In this case, the two database will each +have JobIds that match those in another database. For a unique reference to a +Job, see Job below. + +The Name field of the Job record corresponds to the Name resource record given +in the Director's configuration file. Thus it is a generic name, and it will +be normal to find many Jobs (or even all Jobs) with the same Name. + +The Job field contains a combination of the Name and the schedule time of the +Job by the Director. Thus for a given Director, even with multiple Catalog +databases, the Job will contain a unique name that represents the Job. + +For a given Storage daemon, the VolSessionId and VolSessionTime form a unique +identification of the Job. This will be the case even if multiple Directors +are using the same Storage daemon. + +The Job Type (or simply Type) can have one of the following values: + +\addcontentsline{lot}{table}{Job Types} +\begin{longtable}{|l|l|} + \hline +\multicolumn{1}{|c| }{\bf Value } & \multicolumn{1}{c| }{\bf Meaning } \\ + \hline +{B } & {Backup Job } \\ + \hline +{V } & {Verify Job } \\ + \hline +{R } & {Restore Job } \\ + \hline +{C } & {Console program (not in database) } \\ + \hline +{D } & {Admin Job } \\ + \hline +{A } & {Archive Job (not implemented) } +\\ \hline + +\end{longtable} + +The JobStatus field specifies how the job terminated, and can be one of the +following: + +\addcontentsline{lot}{table}{Job Statuses} +\begin{longtable}{|l|l|} + \hline +\multicolumn{1}{|c| }{\bf Value } & \multicolumn{1}{c| }{\bf Meaning } \\ + \hline +{C } & {Created but not yet running } \\ + \hline +{R } & {Running } \\ + \hline +{B } & {Blocked } \\ + \hline +{T } & {Terminated normally } \\ + \hline +{E } & {Terminated in Error } \\ + \hline +{e } & {Non-fatal error } \\ + \hline +{f } & {Fatal error } \\ + \hline +{D } & {Verify Differences } \\ + \hline +{A } & {Canceled by the user } \\ + \hline +{F } & {Waiting on the File daemon } \\ + \hline +{S } & {Waiting on the Storage daemon } \\ + \hline +{m } & {Waiting for a new Volume to be mounted } \\ + \hline +{M } & {Waiting for a Mount } \\ + \hline +{s } & {Waiting for Storage resource } \\ + \hline +{j } & {Waiting for Job resource } \\ + \hline +{c } & {Waiting for Client resource } \\ + \hline +{d } & {Wating for Maximum jobs } \\ + \hline +{t } & {Waiting for Start Time } \\ + \hline +{p } & {Waiting for higher priority job to finish } +\\ \hline + +\end{longtable} + +\ + +\addcontentsline{lot}{table}{File Sets Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf FileSet } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\ +\ \ } & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{FileSetId } & {integer } & {Primary Key } \\ + \hline +{FileSet } & {tinyblob } & {FileSet name } \\ + \hline +{MD5 } & {tinyblob } & {MD5 checksum of FileSet } \\ + \hline +{CreateTime } & {datetime } & {Time and date Fileset created } +\\ \hline + +\end{longtable} + +The {\bf FileSet} table contains one entry for each FileSet that is used. The +MD5 signature is kept to ensure that if the user changes anything inside the +FileSet, it will be detected and the new FileSet will be used. This is +particularly important when doing an incremental update. If the user deletes a +file or adds a file, we need to ensure that a Full backup is done prior to the +next incremental. + +\ + +\addcontentsline{lot}{table}{JobMedia Table Layout} +\begin{longtable}{|l|l|p{2.5in}|} + \hline +\multicolumn{3}{|l| }{\bf JobMedia } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\ +\ \ } & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{JobMediaId } & {integer } & {Primary Key } \\ + \hline +{JobId } & {integer } & {Link to Job Record } \\ + \hline +{MediaId } & {integer } & {Link to Media Record } \\ + \hline +{FirstIndex } & {integer } & {The index (sequence number) of the first file +written for this Job to the Media } \\ + \hline +{LastIndex } & {integer } & {The index of the last file written for this +Job to the Media } \\ + \hline +{StartFile } & {integer } & {The physical media (tape) file number of the +first block written for this Job } \\ + \hline +{EndFile } & {integer } & {The physical media (tape) file number of the +last block written for this Job } \\ + \hline +{StartBlock } & {integer } & {The number of the first block written for +this Job } \\ + \hline +{EndBlock } & {integer } & {The number of the last block written for this +Job } \\ + \hline +{VolIndex } & {integer } & {The Volume use sequence number within the Job } +\\ \hline + +\end{longtable} + +The {\bf JobMedia} table contains one entry at the following: start of +the job, start of each new tape file, start of each new tape, end of the +job. Since by default, a new tape file is written every 2GB, in general, +you will have more than 2 JobMedia records per Job. The number can be +varied by changing the "Maximum File Size" specified in the Device +resource. This record allows Bacula to efficiently position close to +(within 2GB) any given file in a backup. For restoring a full Job, +these records are not very important, but if you want to retrieve +a single file that was written near the end of a 100GB backup, the +JobMedia records can speed it up by orders of magnitude by permitting +forward spacing files and blocks rather than reading the whole 100GB +backup. + + + +\ + +\addcontentsline{lot}{table}{Media Table Layout} +\begin{longtable}{|l|l|p{2.4in}|} + \hline +\multicolumn{3}{|l| }{\bf Media } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type\ +\ \ } & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{MediaId } & {integer } & {Primary Key } \\ + \hline +{VolumeName } & {tinyblob } & {Volume name } \\ + \hline +{Slot } & {integer } & {Autochanger Slot number or zero } \\ + \hline +{PoolId } & {integer } & {Link to Pool Record } \\ + \hline +{MediaType } & {tinyblob } & {The MediaType supplied by the user } \\ + \hline +{FirstWritten } & {datetime } & {Time/date when first written } \\ + \hline +{LastWritten } & {datetime } & {Time/date when last written } \\ + \hline +{LabelDate } & {datetime } & {Time/date when tape labeled } \\ + \hline +{VolJobs } & {integer } & {Number of jobs written to this media } \\ + \hline +{VolFiles } & {integer } & {Number of files written to this media } \\ + \hline +{VolBlocks } & {integer } & {Number of blocks written to this media } \\ + \hline +{VolMounts } & {integer } & {Number of time media mounted } \\ + \hline +{VolBytes } & {bigint } & {Number of bytes saved in Job } \\ + \hline +{VolErrors } & {integer } & {Number of errors during Job } \\ + \hline +{VolWrites } & {integer } & {Number of writes to media } \\ + \hline +{MaxVolBytes } & {bigint } & {Maximum bytes to put on this media } \\ + \hline +{VolCapacityBytes } & {bigint } & {Capacity estimate for this volume } \\ + \hline +{VolStatus } & {enum } & {Status of media: Full, Archive, Append, Recycle, +Read-Only, Disabled, Error, Busy } \\ + \hline +{Recycle } & {tinyint } & {Whether or not Bacula can recycle the Volumes: +Yes, No } \\ + \hline +{VolRetention } & {bigint } & {64 bit seconds until expiration } \\ + \hline +{VolUseDuration } & {bigint } & {64 bit seconds volume can be used } \\ + \hline +{MaxVolJobs } & {integer } & {maximum jobs to put on Volume } \\ + \hline +{MaxVolFiles } & {integer } & {maximume EOF marks to put on Volume } +\\ \hline + +\end{longtable} + +The {\bf Volume} table (internally referred to as the Media table) contains +one entry for each volume, that is each tape, cassette (8mm, DLT, DAT, ...), +or file on which information is or was backed up. There is one Volume record +created for each of the NumVols specified in the Pool resource record. + +\ + +\addcontentsline{lot}{table}{Pool Table Layout} +\begin{longtable}{|l|l|p{2.4in}|} + \hline +\multicolumn{3}{|l| }{\bf Pool } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{PoolId } & {integer } & {Primary Key } \\ + \hline +{Name } & {Tinyblob } & {Pool Name } \\ + \hline +{NumVols } & {Integer } & {Number of Volumes in the Pool } \\ + \hline +{MaxVols } & {Integer } & {Maximum Volumes in the Pool } \\ + \hline +{UseOnce } & {tinyint } & {Use volume once } \\ + \hline +{UseCatalog } & {tinyint } & {Set to use catalog } \\ + \hline +{AcceptAnyVolume } & {tinyint } & {Accept any volume from Pool } \\ + \hline +{VolRetention } & {bigint } & {64 bit seconds to retain volume } \\ + \hline +{VolUseDuration } & {bigint } & {64 bit seconds volume can be used } \\ + \hline +{MaxVolJobs } & {integer } & {max jobs on volume } \\ + \hline +{MaxVolFiles } & {integer } & {max EOF marks to put on Volume } \\ + \hline +{MaxVolBytes } & {bigint } & {max bytes to write on Volume } \\ + \hline +{AutoPrune } & {tinyint } & {yes|no for autopruning } \\ + \hline +{Recycle } & {tinyint } & {yes|no for allowing auto recycling of Volume } +\\ + \hline +{PoolType } & {enum } & {Backup, Copy, Cloned, Archive, Migration } \\ + \hline +{LabelFormat } & {Tinyblob } & {Label format } +\\ \hline + +\end{longtable} + +The {\bf Pool} table contains one entry for each media pool controlled by +Bacula in this database. One media record exists for each of the NumVols +contained in the Pool. The PoolType is a Bacula defined keyword. The MediaType +is defined by the administrator, and corresponds to the MediaType specified in +the Director's Storage definition record. The CurrentVol is the sequence +number of the Media record for the current volume. + +\ + +\addcontentsline{lot}{table}{Client Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf Client } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{ClientId } & {integer } & {Primary Key } \\ + \hline +{Name } & {TinyBlob } & {File Services Name } \\ + \hline +{UName } & {TinyBlob } & {uname -a from Client (not yet used) } \\ + \hline +{AutoPrune } & {tinyint } & {yes|no for autopruning } \\ + \hline +{FileRetention } & {bigint } & {64 bit seconds to retain Files } \\ + \hline +{JobRetention } & {bigint } & {64 bit seconds to retain Job } +\\ \hline + +\end{longtable} + +The {\bf Client} table contains one entry for each machine backed up by Bacula +in this database. Normally the Name is a fully qualified domain name. + +\ + +\addcontentsline{lot}{table}{Unsaved Files Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf UnsavedFiles } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{UnsavedId } & {integer } & {Primary Key } \\ + \hline +{JobId } & {integer } & {JobId corresponding to this record } \\ + \hline +{PathId } & {integer } & {Id of path } \\ + \hline +{FilenameId } & {integer } & {Id of filename } +\\ \hline + +\end{longtable} + +The {\bf UnsavedFiles} table contains one entry for each file that was not +saved. Note! This record is not yet implemented. + +\ + +\addcontentsline{lot}{table}{Counter Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf Counter } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{Counter } & {tinyblob } & {Counter name } \\ + \hline +{MinValue } & {integer } & {Start/Min value for counter } \\ + \hline +{MaxValue } & {integer } & {Max value for counter } \\ + \hline +{CurrentValue } & {integer } & {Current counter value } \\ + \hline +{WrapCounter } & {tinyblob } & {Name of another counter } +\\ \hline + +\end{longtable} + +The {\bf Counter} table contains one entry for each permanent counter defined +by the user. + +\ + +\addcontentsline{lot}{table}{Version Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf Version } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{VersionId } & {integer } & {Primary Key } +\\ \hline + +\end{longtable} + +The {\bf Version} table defines the Bacula database version number. Bacula +checks this number before reading the database to ensure that it is compatible +with the Bacula binary file. + +\ + +\addcontentsline{lot}{table}{Base Files Table Layout} +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{3}{|l| }{\bf BaseFiles } \\ + \hline +\multicolumn{1}{|c| }{\bf Column Name } & \multicolumn{1}{c| }{\bf Data Type +} & \multicolumn{1}{c| }{\bf Remark } \\ + \hline +{BaseId } & {integer } & {Primary Key } \\ + \hline +{BaseJobId } & {integer } & {JobId of Base Job } \\ + \hline +{JobId } & {integer } & {Reference to Job } \\ + \hline +{FileId } & {integer } & {Reference to File } \\ + \hline +{FileIndex } & {integer } & {File Index number } +\\ \hline + +\end{longtable} + +The {\bf BaseFiles} table contains all the File references for a particular +JobId that point to a Base file -- i.e. they were previously saved and hence +were not saved in the current JobId but in BaseJobId under FileId. FileIndex +is the index of the file, and is used for optimization of Restore jobs to +prevent the need to read the FileId record when creating the in memory tree. +This record is not yet implemented. + +\ + +\subsection{MySQL Table Definition} +\index[general]{MySQL Table Definition } +\index[general]{Definition!MySQL Table } +\addcontentsline{toc}{subsubsection}{MySQL Table Definition} + +The commands used to create the MySQL tables are as follows: + +\footnotesize +\begin{verbatim} +USE bacula; +CREATE TABLE Filename ( + FilenameId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + Name BLOB NOT NULL, + PRIMARY KEY(FilenameId), + INDEX (Name(30)) + ); +CREATE TABLE Path ( + PathId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + Path BLOB NOT NULL, + PRIMARY KEY(PathId), + INDEX (Path(50)) + ); +CREATE TABLE File ( + FileId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + FileIndex INTEGER UNSIGNED NOT NULL DEFAULT 0, + JobId INTEGER UNSIGNED NOT NULL REFERENCES Job, + PathId INTEGER UNSIGNED NOT NULL REFERENCES Path, + FilenameId INTEGER UNSIGNED NOT NULL REFERENCES Filename, + MarkId INTEGER UNSIGNED NOT NULL DEFAULT 0, + LStat TINYBLOB NOT NULL, + MD5 TINYBLOB NOT NULL, + PRIMARY KEY(FileId), + INDEX (JobId), + INDEX (PathId), + INDEX (FilenameId) + ); +CREATE TABLE Job ( + JobId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + Job TINYBLOB NOT NULL, + Name TINYBLOB NOT NULL, + Type BINARY(1) NOT NULL, + Level BINARY(1) NOT NULL, + ClientId INTEGER NOT NULL REFERENCES Client, + JobStatus BINARY(1) NOT NULL, + SchedTime DATETIME NOT NULL, + StartTime DATETIME NOT NULL, + EndTime DATETIME NOT NULL, + JobTDate BIGINT UNSIGNED NOT NULL, + VolSessionId INTEGER UNSIGNED NOT NULL DEFAULT 0, + VolSessionTime INTEGER UNSIGNED NOT NULL DEFAULT 0, + JobFiles INTEGER UNSIGNED NOT NULL DEFAULT 0, + JobBytes BIGINT UNSIGNED NOT NULL, + JobErrors INTEGER UNSIGNED NOT NULL DEFAULT 0, + JobMissingFiles INTEGER UNSIGNED NOT NULL DEFAULT 0, + PoolId INTEGER UNSIGNED NOT NULL REFERENCES Pool, + FileSetId INTEGER UNSIGNED NOT NULL REFERENCES FileSet, + PurgedFiles TINYINT NOT NULL DEFAULT 0, + HasBase TINYINT NOT NULL DEFAULT 0, + PRIMARY KEY(JobId), + INDEX (Name(128)) + ); +CREATE TABLE FileSet ( + FileSetId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + FileSet TINYBLOB NOT NULL, + MD5 TINYBLOB NOT NULL, + CreateTime DATETIME NOT NULL, + PRIMARY KEY(FileSetId) + ); +CREATE TABLE JobMedia ( + JobMediaId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + JobId INTEGER UNSIGNED NOT NULL REFERENCES Job, + MediaId INTEGER UNSIGNED NOT NULL REFERENCES Media, + FirstIndex INTEGER UNSIGNED NOT NULL DEFAULT 0, + LastIndex INTEGER UNSIGNED NOT NULL DEFAULT 0, + StartFile INTEGER UNSIGNED NOT NULL DEFAULT 0, + EndFile INTEGER UNSIGNED NOT NULL DEFAULT 0, + StartBlock INTEGER UNSIGNED NOT NULL DEFAULT 0, + EndBlock INTEGER UNSIGNED NOT NULL DEFAULT 0, + VolIndex INTEGER UNSIGNED NOT NULL DEFAULT 0, + PRIMARY KEY(JobMediaId), + INDEX (JobId, MediaId) + ); +CREATE TABLE Media ( + MediaId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + VolumeName TINYBLOB NOT NULL, + Slot INTEGER NOT NULL DEFAULT 0, + PoolId INTEGER UNSIGNED NOT NULL REFERENCES Pool, + MediaType TINYBLOB NOT NULL, + FirstWritten DATETIME NOT NULL, + LastWritten DATETIME NOT NULL, + LabelDate DATETIME NOT NULL, + VolJobs INTEGER UNSIGNED NOT NULL DEFAULT 0, + VolFiles INTEGER UNSIGNED NOT NULL DEFAULT 0, + VolBlocks INTEGER UNSIGNED NOT NULL DEFAULT 0, + VolMounts INTEGER UNSIGNED NOT NULL DEFAULT 0, + VolBytes BIGINT UNSIGNED NOT NULL DEFAULT 0, + VolErrors INTEGER UNSIGNED NOT NULL DEFAULT 0, + VolWrites INTEGER UNSIGNED NOT NULL DEFAULT 0, + VolCapacityBytes BIGINT UNSIGNED NOT NULL, + VolStatus ENUM('Full', 'Archive', 'Append', 'Recycle', 'Purged', + 'Read-Only', 'Disabled', 'Error', 'Busy', 'Used', 'Cleaning') NOT NULL, + Recycle TINYINT NOT NULL DEFAULT 0, + VolRetention BIGINT UNSIGNED NOT NULL DEFAULT 0, + VolUseDuration BIGINT UNSIGNED NOT NULL DEFAULT 0, + MaxVolJobs INTEGER UNSIGNED NOT NULL DEFAULT 0, + MaxVolFiles INTEGER UNSIGNED NOT NULL DEFAULT 0, + MaxVolBytes BIGINT UNSIGNED NOT NULL DEFAULT 0, + InChanger TINYINT NOT NULL DEFAULT 0, + MediaAddressing TINYINT NOT NULL DEFAULT 0, + VolReadTime BIGINT UNSIGNED NOT NULL DEFAULT 0, + VolWriteTime BIGINT UNSIGNED NOT NULL DEFAULT 0, + PRIMARY KEY(MediaId), + INDEX (PoolId) + ); +CREATE TABLE Pool ( + PoolId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + Name TINYBLOB NOT NULL, + NumVols INTEGER UNSIGNED NOT NULL DEFAULT 0, + MaxVols INTEGER UNSIGNED NOT NULL DEFAULT 0, + UseOnce TINYINT NOT NULL, + UseCatalog TINYINT NOT NULL, + AcceptAnyVolume TINYINT DEFAULT 0, + VolRetention BIGINT UNSIGNED NOT NULL, + VolUseDuration BIGINT UNSIGNED NOT NULL, + MaxVolJobs INTEGER UNSIGNED NOT NULL DEFAULT 0, + MaxVolFiles INTEGER UNSIGNED NOT NULL DEFAULT 0, + MaxVolBytes BIGINT UNSIGNED NOT NULL, + AutoPrune TINYINT DEFAULT 0, + Recycle TINYINT DEFAULT 0, + PoolType ENUM('Backup', 'Copy', 'Cloned', 'Archive', 'Migration', 'Scratch') NOT NULL, + LabelFormat TINYBLOB, + Enabled TINYINT DEFAULT 1, + ScratchPoolId INTEGER UNSIGNED DEFAULT 0 REFERENCES Pool, + RecyclePoolId INTEGER UNSIGNED DEFAULT 0 REFERENCES Pool, + UNIQUE (Name(128)), + PRIMARY KEY (PoolId) + ); +CREATE TABLE Client ( + ClientId INTEGER UNSIGNED NOT NULL AUTO_INCREMENT, + Name TINYBLOB NOT NULL, + Uname TINYBLOB NOT NULL, /* full uname -a of client */ + AutoPrune TINYINT DEFAULT 0, + FileRetention BIGINT UNSIGNED NOT NULL, + JobRetention BIGINT UNSIGNED NOT NULL, + UNIQUE (Name(128)), + PRIMARY KEY(ClientId) + ); +CREATE TABLE BaseFiles ( + BaseId INTEGER UNSIGNED AUTO_INCREMENT, + BaseJobId INTEGER UNSIGNED NOT NULL REFERENCES Job, + JobId INTEGER UNSIGNED NOT NULL REFERENCES Job, + FileId INTEGER UNSIGNED NOT NULL REFERENCES File, + FileIndex INTEGER UNSIGNED, + PRIMARY KEY(BaseId) + ); +CREATE TABLE UnsavedFiles ( + UnsavedId INTEGER UNSIGNED AUTO_INCREMENT, + JobId INTEGER UNSIGNED NOT NULL REFERENCES Job, + PathId INTEGER UNSIGNED NOT NULL REFERENCES Path, + FilenameId INTEGER UNSIGNED NOT NULL REFERENCES Filename, + PRIMARY KEY (UnsavedId) + ); +CREATE TABLE Version ( + VersionId INTEGER UNSIGNED NOT NULL + ); +-- Initialize Version +INSERT INTO Version (VersionId) VALUES (7); +CREATE TABLE Counters ( + Counter TINYBLOB NOT NULL, + MinValue INTEGER, + MaxValue INTEGER, + CurrentValue INTEGER, + WrapCounter TINYBLOB NOT NULL, + PRIMARY KEY (Counter(128)) + ); +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/developers/check_tex.pl b/docs/manuals/fr/developers/check_tex.pl new file mode 100755 index 00000000..e12d51be --- /dev/null +++ b/docs/manuals/fr/developers/check_tex.pl @@ -0,0 +1,152 @@ +#!/usr/bin/perl -w +# Finds potential problems in tex files, and issues warnings to the console +# about what it finds. Takes a list of files as its only arguments, +# and does checks on all the files listed. The assumption is that these are +# valid (or close to valid) LaTeX files. It follows \include statements +# recursively to pick up any included tex files. +# +# +# +# Currently the following checks are made: +# +# -- Multiple hyphens not inside a verbatim environment (or \verb). These +# should be placed inside a \verb{} contruct so they will not be converted +# to single hyphen by latex and latex2html. + + +# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com +# +# + +use strict; + +# The following builds the test string to identify and change multiple +# hyphens in the tex files. Several constructs are identified but only +# multiple hyphens are changed; the others are fed to the output +# unchanged. +my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{ +my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{ +my $c = '\\s*\\}'; # closing curly brace + +# This captures entire verbatim environments. These are passed to the output +# file unchanged. +my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c; + +# This captures \verb{..{ constructs. They are passed to the output unchanged. +my $verb = '\\\\verb\\*?(.).*?\\1'; + +# This captures multiple hyphens with a leading and trailing space. These are not changed. +my $hyphsp = '\\s\\-{2,}\\s'; + +# This identifies other multiple hyphens. +my $hyphens = '\\-{2,}'; + +# This identifies \hyperpage{..} commands, which should be ignored. +my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}'; + +# This builds the actual test string from the above strings. +#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens"; +my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens"; + + +sub get_includes { + # Get a list of include files from the top-level tex file. The first + # argument is a pointer to the list of files found. The rest of the + # arguments is a list of filenames to check for includes. + my $files = shift; + my ($fileline,$includefile,$includes); + + while (my $filename = shift) { + # Get a list of all the html files in the directory. + open my $if,"<$filename" or die "Cannot open input file $filename\n"; + $fileline = 0; + $includes = 0; + while (<$if>) { + chomp; + $fileline++; + # If a file is found in an include, process it. + if (($includefile) = /\\include\s*\{(.*?)\}/) { + $includes++; + # Append .tex to the filename + $includefile .= '.tex'; + + # If the include file has already been processed, issue a warning + # and don't do it again. + my $found = 0; + foreach (@$files) { + if ($_ eq $includefile) { + $found = 1; + last; + } + } + if ($found) { + print "$includefile found at line $fileline in $filename was previously included\n"; + } else { + # The file has not been previously found. Save it and + # recursively process it. + push (@$files,$includefile); + get_includes($files,$includefile); + } + } + } + close IF; + } +} + + +sub check_hyphens { + my (@files) = @_; + my ($filedata,$this,$linecnt,$before); + + # Build the test string to check for the various environments. + # We only do the conversion if the multiple hyphens are outside of a + # verbatim environment (either \begin{verbatim}...\end{verbatim} or + # \verb{--}). Capture those environments and pass them to the output + # unchanged. + + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # Set up to process the file data. + $linecnt = 1; + + # Go through the file data from beginning to end. For each match, save what + # came before it and what matched. $filedata now becomes only what came + # after the match. + # Chech the match to see if it starts with a multiple-hyphen. If so + # warn the user. Keep track of line numbers so they can be output + # with the warning message. + while ($filedata =~ /$teststr/os) { + $this = $&; + $before = $`; + $filedata = $'; + $linecnt += $before =~ tr/\n/\n/; + + # Check if the multiple hyphen is present outside of one of the + # acceptable constructs. + if ($this =~ /^\-+/) { + print "Possible unwanted multiple hyphen found in line ", + "$linecnt of file $file\n"; + } + $linecnt += $this =~ tr/\n/\n/; + } + } +} +################################################################## +# MAIN #### +################################################################## + +my (@includes,$cnt); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +get_includes(\@includes,@ARGV); + +check_hyphens(@includes); diff --git a/docs/manuals/fr/developers/daemonprotocol.tex b/docs/manuals/fr/developers/daemonprotocol.tex new file mode 100644 index 00000000..0354bbd5 --- /dev/null +++ b/docs/manuals/fr/developers/daemonprotocol.tex @@ -0,0 +1,284 @@ +%% +%% + +\chapter{Daemon Protocol} +\label{_ChapterStart2} +\index{Protocol!Daemon } +\index{Daemon Protocol } + +\section{General} +\index{General } +\addcontentsline{toc}{subsection}{General} + +This document describes the protocols used between the various daemons. As +Bacula has developed, it has become quite out of date. The general idea still +holds true, but the details of the fields for each command, and indeed the +commands themselves have changed considerably. + +It is intended to be a technical discussion of the general daemon protocols +and as such is not targeted at end users but rather at developers and system +administrators that want or need to know more of the working details of {\bf +Bacula}. + +\section{Low Level Network Protocol} +\index{Protocol!Low Level Network } +\index{Low Level Network Protocol } +\addcontentsline{toc}{subsection}{Low Level Network Protocol} + +At the lowest level, the network protocol is handled by {\bf BSOCK} packets +which contain a lot of information about the status of the network connection: +who is at the other end, etc. Each basic {\bf Bacula} network read or write +actually consists of two low level network read/writes. The first write always +sends four bytes of data in machine independent byte order. If data is to +follow, the first four bytes are a positive non-zero integer indicating the +length of the data that follow in the subsequent write. If the four byte +integer is zero or negative, it indicates a special request, a sort of network +signaling capability. In this case, no data packet will follow. The low level +BSOCK routines expect that only a single thread is accessing the socket at a +time. It is advised that multiple threads do not read/write the same socket. +If you must do this, you must provide some sort of locking mechanism. It would +not be appropriate for efficiency reasons to make every call to the BSOCK +routines lock and unlock the packet. + +\section{General Daemon Protocol} +\index{General Daemon Protocol } +\index{Protocol!General Daemon } +\addcontentsline{toc}{subsection}{General Daemon Protocol} + +In general, all the daemons follow the following global rules. There may be +exceptions depending on the specific case. Normally, one daemon will be +sending commands to another daemon (specifically, the Director to the Storage +daemon and the Director to the File daemon). + +\begin{itemize} +\item Commands are always ASCII commands that are upper/lower case dependent + as well as space sensitive. +\item All binary data is converted into ASCII (either with printf statements + or using base64 encoding). +\item All responses to commands sent are always prefixed with a return + numeric code where codes in the 1000's are reserved for the Director, the + 2000's are reserved for the File daemon, and the 3000's are reserved for the +Storage daemon. +\item Any response that is not prefixed with a numeric code is a command (or + subcommand if you like) coming from the other end. For example, while the + Director is corresponding with the Storage daemon, the Storage daemon can +request Catalog services from the Director. This convention permits each side +to send commands to the other daemon while simultaneously responding to +commands. +\item Any response that is of zero length, depending on the context, either + terminates the data stream being sent or terminates command mode prior to + closing the connection. +\item Any response that is of negative length is a special sign that normally + requires a response. For example, during data transfer from the File daemon + to the Storage daemon, normally the File daemon sends continuously without +intervening reads. However, periodically, the File daemon will send a packet +of length -1 indicating that the current data stream is complete and that the +Storage daemon should respond to the packet with an OK, ABORT JOB, PAUSE, +etc. This permits the File daemon to efficiently send data while at the same +time occasionally ``polling'' the Storage daemon for his status or any +special requests. + +Currently, these negative lengths are specific to the daemon, but shortly, +the range 0 to -999 will be standard daemon wide signals, while -1000 to +-1999 will be for Director user, -2000 to -2999 for the File daemon, and +-3000 to -3999 for the Storage daemon. +\end{itemize} + +\section{The Protocol Used Between the Director and the Storage Daemon} +\index{Daemon!Protocol Used Between the Director and the Storage } +\index{Protocol Used Between the Director and the Storage Daemon } +\addcontentsline{toc}{subsection}{Protocol Used Between the Director and the +Storage Daemon} + +Before sending commands to the File daemon, the Director opens a Message +channel with the Storage daemon, identifies itself and presents its password. +If the password check is OK, the Storage daemon accepts the Director. The +Director then passes the Storage daemon, the JobId to be run as well as the +File daemon authorization (append, read all, or read for a specific session). +The Storage daemon will then pass back to the Director a enabling key for this +JobId that must be presented by the File daemon when opening the job. Until +this process is complete, the Storage daemon is not available for use by File +daemons. + +\footnotesize +\begin{verbatim} +SD: listens +DR: makes connection +DR: Hello calling +SD: 3000 OK Hello +DR: JobId=nnn Allow=(append, read) Session=(*, SessionId) + (Session not implemented yet) +SD: 3000 OK Job Authorization= +DR: use device= media_type= + pool_name= pool_type= +SD: 3000 OK use device +\end{verbatim} +\normalsize + +For the Director to be authorized, the \lt{}Director-name\gt{} and the +\lt{}password\gt{} must match the values in one of the Storage daemon's +Director resources (there may be several Directors that can access a single +Storage daemon). + +\section{The Protocol Used Between the Director and the File Daemon} +\index{Daemon!Protocol Used Between the Director and the File } +\index{Protocol Used Between the Director and the File Daemon } +\addcontentsline{toc}{subsection}{Protocol Used Between the Director and the +File Daemon} + +A typical conversation might look like the following: + +\footnotesize +\begin{verbatim} +FD: listens +DR: makes connection +DR: Hello calling +FD: 2000 OK Hello +DR: JobId=nnn Authorization= +FD: 2000 OK Job +DR: storage address = port = + name = mediatype = +FD: 2000 OK storage +DR: include +DR: +DR: + ... +DR: Null packet +FD: 2000 OK include +DR: exclude +DR: +DR: + ... +DR: Null packet +FD: 2000 OK exclude +DR: full +FD: 2000 OK full +DR: save +FD: 2000 OK save +FD: Attribute record for each file as sent to the + Storage daemon (described above). +FD: Null packet +FD: + e.g. + 3000 OK Volumes = + 3001 Volume = + + 3002 Volume data = + + ... additional Volume / Volume data pairs for volumes 2 .. n +FD: Null packet +FD: close socket +\end{verbatim} +\normalsize + +\section{The Save Protocol Between the File Daemon and the Storage Daemon} +\index{Save Protocol Between the File Daemon and the Storage Daemon } +\index{Daemon!Save Protocol Between the File Daemon and the Storage } +\addcontentsline{toc}{subsection}{Save Protocol Between the File Daemon and +the Storage Daemon} + +Once the Director has send a {\bf save} command to the File daemon, the File +daemon will contact the Storage daemon to begin the save. + +In what follows: FD: refers to information set via the network from the File +daemon to the Storage daemon, and SD: refers to information set from the +Storage daemon to the File daemon. + +\subsection{Command and Control Information} +\index{Information!Command and Control } +\index{Command and Control Information } +\addcontentsline{toc}{subsubsection}{Command and Control Information} + +Command and control information is exchanged in human readable ASCII commands. + + +\footnotesize +\begin{verbatim} +FD: listens +SD: makes connection +FD: append open session = [] +SD: 3000 OK ticket = +FD: append data +SD: 3000 OK data address = port = +\end{verbatim} +\normalsize + +\subsection{Data Information} +\index{Information!Data } +\index{Data Information } +\addcontentsline{toc}{subsubsection}{Data Information} + +The Data information consists of the file attributes and data to the Storage +daemon. For the most part, the data information is sent one way: from the File +daemon to the Storage daemon. This allows the File daemon to transfer +information as fast as possible without a lot of handshaking and network +overhead. + +However, from time to time, the File daemon needs to do a sort of checkpoint +of the situation to ensure that everything is going well with the Storage +daemon. To do so, the File daemon sends a packet with a negative length +indicating that he wishes the Storage daemon to respond by sending a packet of +information to the File daemon. The File daemon then waits to receive a packet +from the Storage daemon before continuing. + +All data sent are in binary format except for the header packet, which is in +ASCII. There are two packet types used data transfer mode: a header packet, +the contents of which are known to the Storage daemon, and a data packet, the +contents of which are never examined by the Storage daemon. + +The first data packet to the Storage daemon will be an ASCII header packet +consisting of the following data. + +\lt{}File-Index\gt{} \lt{}Stream-Id\gt{} \lt{}Info\gt{} where {\bf +\lt{}File-Index\gt{}} is a sequential number beginning from one that +increments with each file (or directory) sent. + +where {\bf \lt{}Stream-Id\gt{}} will be 1 for the Attributes record and 2 for +uncompressed File data. 3 is reserved for the MD5 signature for the file. + +where {\bf \lt{}Info\gt{}} transmit information about the Stream to the +Storage Daemon. It is a character string field where each character has a +meaning. The only character currently defined is 0 (zero), which is simply a +place holder (a no op). In the future, there may be codes indicating +compressed data, encrypted data, etc. + +Immediately following the header packet, the Storage daemon will expect any +number of data packets. The series of data packets is terminated by a zero +length packet, which indicates to the Storage daemon that the next packet will +be another header packet. As previously mentioned, a negative length packet is +a request for the Storage daemon to temporarily enter command mode and send a +reply to the File daemon. Thus an actual conversation might contain the +following exchanges: + +\footnotesize +\begin{verbatim} +FD: <1 1 0> (header packet) +FD: +FD: Null packet +FD: <1 2 0> +FD: +FD: Packet length = -1 +SD: 3000 OK +FD: <2 1 0> +FD: +FD: Null packet +FD: <2 2 0> +FD: +FD: Null packet +FD: Null packet +FD: append end session +SD: 3000 OK end +FD: append close session +SD: 3000 OK Volumes = +SD: 3001 Volume = + +SD: 3002 Volume data = + +SD: ... additional Volume / Volume data pairs for + volumes 2 .. n +FD: close socket +\end{verbatim} +\normalsize + +The information returned to the File daemon by the Storage daemon in response +to the {\bf append close session} is transmit in turn to the Director. diff --git a/docs/manuals/fr/developers/developers.css b/docs/manuals/fr/developers/developers.css new file mode 100644 index 00000000..d1824aff --- /dev/null +++ b/docs/manuals/fr/developers/developers.css @@ -0,0 +1,30 @@ +/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ +.MATH { font-family: "Century Schoolbook", serif; } +.MATH I { font-family: "Century Schoolbook", serif; font-style: italic } +.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold } + +/* implement both fixed-size and relative sizes */ +SMALL.XTINY { font-size : xx-small } +SMALL.TINY { font-size : x-small } +SMALL.SCRIPTSIZE { font-size : smaller } +SMALL.FOOTNOTESIZE { font-size : small } +SMALL.SMALL { } +BIG.LARGE { } +BIG.XLARGE { font-size : large } +BIG.XXLARGE { font-size : x-large } +BIG.HUGE { font-size : larger } +BIG.XHUGE { font-size : xx-large } + +/* heading styles */ +H1 { } +H2 { } +H3 { } +H4 { } +H5 { } + +/* mathematics styles */ +DIV.displaymath { } /* math displays */ +TD.eqno { } /* equation-number cells */ + + +/* document-specific styles come next */ diff --git a/docs/manuals/fr/developers/developers.tex b/docs/manuals/fr/developers/developers.tex new file mode 100644 index 00000000..840b1a0a --- /dev/null +++ b/docs/manuals/fr/developers/developers.tex @@ -0,0 +1,88 @@ +%% +%% + +\documentclass[11pt,a4paper]{report} +\usepackage{html} +\usepackage{float} +\usepackage{graphicx} +\usepackage{bacula} +\usepackage{longtable} +\usepackage{makeidx} +\usepackage{index} +\usepackage{setspace} +\usepackage{hyperref} +\usepackage{url} + + +\makeindex +\newindex{general}{idx}{ind}{General Index} + +\sloppy + +\begin{document} +\sloppy + +\newfont{\bighead}{cmr17 at 36pt} +\parskip 10pt +\parindent 0pt + +\title{\includegraphics{./bacula-logo.eps} \\ \bigskip + \Huge{Developers' Guide} + \begin{center} + \large{It comes in the night and sucks + the essence from your computers. } + \end{center} +} + + +\author{Kern Sibbald} +\date{\vspace{1.0in}\today \\ + This manual documents Bacula version \input{version} \\ + \vspace{0.2in} + Copyright \copyright 1999-2007, Free Software Foundation Europe + e.V. \\ + \vspace{0.2in} + Permission is granted to copy, distribute and/or modify this document under the terms of the + GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU Free Documentation License". +} + + +\maketitle + +\clearpage +\tableofcontents +\clearpage +\listoffigures +\clearpage +\listoftables +\clearpage + +\include{generaldevel} +\include{platformsupport} +\include{daemonprotocol} +\include{director} +\include{file} +\include{storage} +\include{catalog} +\include{mediaformat} +\include{porting} +\include{gui-interface} +\include{tls-techdoc} +\include{regression} +\include{md5} +\include{mempool} +\include{netprotocol} +\include{smartall} +\include{fdl} + + +% The following line tells link_resolver.pl to not include these files: +% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main + +% pull in the index +\clearpage +\printindex + +\end{document} diff --git a/docs/manuals/fr/developers/director.tex b/docs/manuals/fr/developers/director.tex new file mode 100644 index 00000000..d8c4cd0f --- /dev/null +++ b/docs/manuals/fr/developers/director.tex @@ -0,0 +1,18 @@ +%% +%% + +\chapter{Director Services Daemon} +\label{_ChapterStart6} +\index{Daemon!Director Services } +\index{Director Services Daemon } +\addcontentsline{toc}{section}{Director Services Daemon} + +This chapter is intended to be a technical discussion of the Director services +and as such is not targeted at end users but rather at developers and system +administrators that want or need to know more of the working details of {\bf +Bacula}. + +The {\bf Bacula Director} services consist of the program that supervises all +the backup and restore operations. + +To be written ... diff --git a/docs/manuals/fr/developers/fdl.tex b/docs/manuals/fr/developers/fdl.tex new file mode 100644 index 00000000..9304bb60 --- /dev/null +++ b/docs/manuals/fr/developers/fdl.tex @@ -0,0 +1,511 @@ +%---------The file header--------------------------------------------- + +%% \usepackage[english]{babel} %language selection +%% \usepackage[T1]{fontenc} + +%%\pagenumbering{arabic} + +%% \usepackage{hyperref} +%% \hypersetup{colorlinks, +%% citecolor=black, +%% filecolor=black, +%% linkcolor=black, +%% urlcolor=black, +%% pdftex} + + +%--------------------------------------------------------------------- +\chapter{GNU Free Documentation License} +\index[general]{GNU ree Documentation License} +\index[general]{License!GNU ree Documentation} +\addcontentsline{toc}{section}{GNU ree Documentation License} + +%\label{label_fdl} + + \begin{center} + + Version 1.2, November 2002 + + + Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc. + + \bigskip + + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + \bigskip + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +\end{center} + + +\begin{center} +{\bf\large Preamble} +\end{center} + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +\begin{center} +{\Large\bf 1. APPLICABILITY AND DEFINITIONS} +\addcontentsline{toc}{section}{1. APPLICABILITY AND DEFINITIONS} +\end{center} + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The \textbf{"Document"}, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as \textbf{"you"}. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A \textbf{"Modified Version"} of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A \textbf{"Secondary Section"} is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The \textbf{"Cover Texts"} are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A \textbf{"Transparent"} copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called \textbf{"Opaque"}. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The \textbf{"Title Page"} means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as \textbf{"Acknowledgements"}, +\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.) +To \textbf{"Preserve the Title"} +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +\begin{center} +{\Large\bf 2. VERBATIM COPYING} +\addcontentsline{toc}{section}{2. VERBATIM COPYING} +\end{center} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\begin{center} +{\Large\bf 3. COPYING IN QUANTITY} +\addcontentsline{toc}{section}{3. COPYING IN QUANTITY} +\end{center} + + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\begin{center} +{\Large\bf 4. MODIFICATIONS} +\addcontentsline{toc}{section}{4. MODIFICATIONS} +\end{center} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} +\item[A.] + Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. + +\item[B.] + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + +\item[C.] + State on the Title page the name of the publisher of the + Modified Version, as the publisher. + +\item[D.] + Preserve all the copyright notices of the Document. + +\item[E.] + Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + +\item[F.] + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + +\item[G.] + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. + +\item[H.] + Include an unaltered copy of this License. + +\item[I.] + Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + +\item[J.] + Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + +\item[K.] + For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + +\item[L.] + Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. + +\item[M.] + Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + +\item[N.] + Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. + +\item[O.] + Preserve any Warranty Disclaimers. +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\begin{center} +{\Large\bf 5. COMBINING DOCUMENTS} +\addcontentsline{toc}{section}{5. COMBINING DOCUMENTS} +\end{center} + + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + +\begin{center} +{\Large\bf 6. COLLECTIONS OF DOCUMENTS} +\addcontentsline{toc}{section}{6. COLLECTIONS OF DOCUMENTS} +\end{center} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +\begin{center} +{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS} +\addcontentsline{toc}{section}{7. AGGREGATION WITH INDEPENDENT WORKS} +\end{center} + + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +\begin{center} +{\Large\bf 8. TRANSLATION} +\addcontentsline{toc}{section}{8. TRANSLATION} +\end{center} + + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +\begin{center} +{\Large\bf 9. TERMINATION} +\addcontentsline{toc}{section}{9. TERMINATION} +\end{center} + + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\begin{center} +{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE} +\addcontentsline{toc}{section}{10. FUTURE REVISIONS OF THIS LICENSE} +\end{center} + + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +\begin{center} +{\Large\bf ADDENDUM: How to use this License for your documents} +\addcontentsline{toc}{section}{ADDENDUM: How to use this License for your documents} +\end{center} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\bigskip +\begin{quote} + Copyright \copyright YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +\end{quote} +\bigskip + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + +\bigskip +\begin{quote} + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. +\end{quote} +\bigskip + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +%--------------------------------------------------------------------- diff --git a/docs/manuals/fr/developers/file.tex b/docs/manuals/fr/developers/file.tex new file mode 100644 index 00000000..ee89577b --- /dev/null +++ b/docs/manuals/fr/developers/file.tex @@ -0,0 +1,68 @@ +%% +%% + +\chapter{File Services Daemon} +\label{_ChapterStart11} +\index{File Services Daemon } +\index{Daemon!File Services } +\addcontentsline{toc}{section}{File Services Daemon} + +Please note, this section is somewhat out of date as the code has evolved +significantly. The basic idea has not changed though. + +This chapter is intended to be a technical discussion of the File daemon +services and as such is not targeted at end users but rather at developers and +system administrators that want or need to know more of the working details of +{\bf Bacula}. + +The {\bf Bacula File Services} consist of the programs that run on the system +to be backed up and provide the interface between the Host File system and +Bacula -- in particular, the Director and the Storage services. + +When time comes for a backup, the Director gets in touch with the File daemon +on the client machine and hands it a set of ``marching orders'' which, if +written in English, might be something like the following: + +OK, {\bf File daemon}, it's time for your daily incremental backup. I want you +to get in touch with the Storage daemon on host archive.mysite.com and perform +the following save operations with the designated options. You'll note that +I've attached include and exclude lists and patterns you should apply when +backing up the file system. As this is an incremental backup, you should save +only files modified since the time you started your last backup which, as you +may recall, was 2000-11-19-06:43:38. Please let me know when you're done and +how it went. Thank you. + +So, having been handed everything it needs to decide what to dump and where to +store it, the File daemon doesn't need to have any further contact with the +Director until the backup is complete providing there are no errors. If there +are errors, the error messages will be delivered immediately to the Director. +While the backup is proceeding, the File daemon will send the file coordinates +and data for each file being backed up to the Storage daemon, which will in +turn pass the file coordinates to the Director to put in the catalog. + +During a {\bf Verify} of the catalog, the situation is different, since the +File daemon will have an exchange with the Director for each file, and will +not contact the Storage daemon. + +A {\bf Restore} operation will be very similar to the {\bf Backup} except that +during the {\bf Restore} the Storage daemon will not send storage coordinates +to the Director since the Director presumably already has them. On the other +hand, any error messages from either the Storage daemon or File daemon will +normally be sent directly to the Directory (this, of course, depends on how +the Message resource is defined). + +\section{Commands Received from the Director for a Backup} +\index{Backup!Commands Received from the Director for a } +\index{Commands Received from the Director for a Backup } +\addcontentsline{toc}{subsection}{Commands Received from the Director for a +Backup} + +To be written ... + +\section{Commands Received from the Director for a Restore} +\index{Commands Received from the Director for a Restore } +\index{Restore!Commands Received from the Director for a } +\addcontentsline{toc}{subsection}{Commands Received from the Director for a +Restore} + +To be written ... diff --git a/docs/manuals/fr/developers/fix_tex.pl b/docs/manuals/fr/developers/fix_tex.pl new file mode 100755 index 00000000..98657576 --- /dev/null +++ b/docs/manuals/fr/developers/fix_tex.pl @@ -0,0 +1,184 @@ +#!/usr/bin/perl -w +# Fixes various things within tex files. + +use strict; + +my %args; + + +sub get_includes { + # Get a list of include files from the top-level tex file. + my (@list,$file); + + foreach my $filename (@_) { + $filename or next; + # Start with the top-level latex file so it gets checked too. + push (@list,$filename); + + # Get a list of all the html files in the directory. + open IF,"<$filename" or die "Cannot open input file $filename"; + while () { + chomp; + push @list,"$1.tex" if (/\\include\{(.*?)\}/); + } + + close IF; + } + return @list; +} + +sub convert_files { + my (@files) = @_; + my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt); + + $cnt = 0; + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # We look for a line that starts with \item, and indent the two next lines (if not blank) + # by three spaces. + my $linecnt = 3; + $indentcnt = 0; + $output = ""; + # Process a line at a time. + foreach (split(/\n/,$filedata)) { + $_ .= "\n"; # Put back the return. + # If this line is less than the third line past the \item command, + # and the line isn't blank and doesn't start with whitespace + # add three spaces to the start of the line. Keep track of the number + # of lines changed. + if ($linecnt < 3 and !/^\\item/) { + if (/^[^\n\s]/) { + $output .= " " . $_; + $indentcnt++; + } else { + $output .= $_; + } + $linecnt++; + } else { + $linecnt = 3; + $output .= $_; + } + /^\\item / and $linecnt = 1; + } + + + # This is an item line. We need to process it too. If inside a \begin{description} environment, convert + # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'. + $itemcnt = 0; + $filedata = $output; + $output = ""; + my ($before,$descrip,$this,$between); + + # Find any \begin{description} environment + while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) { + $output .= $` . $1; + $filedata = $3 . $'; + $descrip = $2; + + # Search for \item {\bf xxx} + while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) { + $descrip = $'; + $output .= $`; + ($between,$descrip) = find_matching_brace($descrip); + if (!$descrip) { + $linecnt = $output =~ tr/\n/\n/; + print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip); + } + + # Now do the replacement. + $between = '{' . $between . '}' if ($between =~ /\[|\]/); + $output .= "\\item \[$between\]"; + $itemcnt++; + } + $output .= $descrip; + } + $output .= $filedata; + + # If any hyphens or \item commnads were converted, save the file. + if ($indentcnt or $itemcnt) { + open OF,">$file" or die "Cannot open output file $file"; + print OF $output; + close OF; + print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n"; + print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n"; + } + + $cnt += $indentcnt + $itemcnt; + } + return $cnt; +} + +sub find_matching_brace { + # Finds text up to the next matching brace. Assumes that the input text doesn't contain + # the opening brace, but we want to find text up to a matching closing one. + # Returns the text between the matching braces, followed by the rest of the text following + # (which does not include the matching brace). + # + my $str = shift; + my ($this,$temp); + my $cnt = 1; + + while ($cnt) { + # Ignore verbatim constructs involving curly braces, or if the character preceding + # the curly brace is a backslash. + if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) { + $this .= $`; + $str = $'; + $temp = $&; + + if ((substr($this,-1,1) eq '\\') or + $temp =~ /^\\verb/) { + $this .= $temp; + next; + } + + $cnt += ($temp eq '{') ? 1 : -1; + # If this isn't the matching curly brace ($cnt > 0), include the brace. + $this .= $temp if ($cnt); + } else { + # No matching curly brace found. + return ($this . $str,''); + } + } + return ($this,$str); +} + +sub check_arguments { + # Checks command-line arguments for ones starting with -- puts them into + # a hash called %args and removes them from @ARGV. + my $args = shift; + my $i; + + for ($i = 0; $i < $#ARGV; $i++) { + $ARGV[$i] =~ /^\-+/ or next; + $ARGV[$i] =~ s/^\-+//; + $args{$ARGV[$i]} = ""; + delete ($ARGV[$i]); + + } +} + +################################################################## +# MAIN #### +################################################################## + +my @includes; +my $cnt; + +check_arguments(\%args); +die "No Files given to Check\n" if ($#ARGV < 0); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +@includes = get_includes(@ARGV); + +$cnt = convert_files(@includes); +print "No lines changed\n" unless $cnt; diff --git a/docs/manuals/fr/developers/generaldevel.tex b/docs/manuals/fr/developers/generaldevel.tex new file mode 100644 index 00000000..9404e57e --- /dev/null +++ b/docs/manuals/fr/developers/generaldevel.tex @@ -0,0 +1,1403 @@ +%% +%% + +\chapter{Bacula Developer Notes} +\label{_ChapterStart10} +\index{Bacula Developer Notes} +\index{Notes!Bacula Developer} +\addcontentsline{toc}{section}{Bacula Developer Notes} + +\section{General} +\index{General} +\addcontentsline{toc}{subsection}{General} + +This document is intended mostly for developers and describes the the general +framework of making Bacula source changes. + +\subsection{Contributions} +\index{Contributions} +\addcontentsline{toc}{subsubsection}{Contributions} + +Contributions from programmers are broken into two groups. The first are +contributions that are aids and not essential to Bacula. In general, these +will be scripts or will go into and examples or contributions directory. +For these kinds of non-essential contributions there is no obligation to do +a copyright assignment as described below. However, a copyright assignment +would still be appreciated. + +The second class of contributions are those which will be integrated with +Bacula and become an essential part. Within this class of contributions, there +are two hurdles to surmount. One is getting your patch accepted, and two is +dealing with copyright issues. The following text describes some of the +requirements for such code. + +\subsection{Patches} +\index{Patches} +\addcontentsline{toc}{subsubsection}{Patches} + +Subject to the copyright assignment described below, your patches should be +sent in {\bf diff -u} format relative to the current contents of the Source +Forge SVN, which is the easiest to understand and integrate. +Please be sure to use the Bacula indenting standard (see below). +If you have checked out the source with SVN, you can get a diff using: + +\begin{verbatim} +svn update +svn diff > change.patch +\end{verbatim} + +If you plan on doing significant development work over a period of time, +after having your first patch reviewed and approved, you will be eligible +for having developer SVN access so that you can commit your changes +directly to the SVN repository. To do so, you will need a userid on Source +Forge. + +\subsection{Copyrights} +\index{Copyrights} +\addcontentsline{toc}{subsubsection}{Copyrights} + +To avoid future problems concerning changing licensing or +copyrights, all code contributions more than a hand full of lines +must be in the Public Domain or have the copyright transferred to +the Free Software Foundation Europe e.V. with a Fiduciary License +Agreement (FLA) as in the current code. Note, prior to +November 2004, the code was copyrighted by Kern Sibbald and John +Walker. After November 2004, the code was copyrighted by Kern +Sibbald, then on the 15th of November 2006, the copyright was +transferred to the Free Software Foundation Europe e.V. + +Your name should be clearly indicated as the author of the code, and you +must be extremely careful not to violate any copyrights or use other +people's code without acknowledging it. The purpose of this requirement is +to avoid future copyright, patent, or intellectual property problems. +Please read the LICENSE agreement in the main source code +directory. When you sign the Fiduciary License Agreement (FLA) +and send it in, you are argeeing to the terms of that LICENSE +file. + +To understand the possible source of future problems, please +examine the difficulties Mozilla is (was?) having finding +previous contributors at \elink{ +http://www.mozilla.org/MPL/missing.html} +{http://www.mozilla.org/MPL/missing.html}. The other important issue is to +avoid copyright, patent, or intellectual property violations as are currently +(May 2003) being claimed by SCO against IBM. + +Although the copyright will be held by the Free Software +Foundation Europe e.V., each developer is expected to indicate +that he wrote and/or modified a particular module (or file) and +any other sources. The copyright assignment may seem a bit +unusual, but in reality, it is not. Most large projects require +this. + +If you have any doubts about this, please don't hesitate to ask. The +objective is to assure the long term servival of the Bacula project. + +Items not needing a copyright assignment are: most small changes, +enhancements, or bug fixes of 5-10 lines of code, which amount to +less than 20% of any particular file. + +\subsection{Copyright Assignment -- Fiduciary License Agreement} +\index{Copyright Assignment} +\index{Assignment!Copyright} +\addcontentsline{toc}{subsubsection}{Copyright Assignment -- Fiduciary License Agreement} + +Since this is not a commercial enterprise, and we prefer to believe in +everyone's good faith, previously developers could assign the copyright by +explicitly acknowledging that they do so in their first submission. This +was sufficient if the developer is independent, or an employee of a +not-for-profit organization or a university. However, in an effort to +ensure that the Bacula code is really clean, beginning in August 2006, all +previous and future developers with SVN access will be asked to submit a +copyright assignment (or Fiduciary License Agreement -- FLA), +which means you agree to the LICENSE in the main source +directory. It also means that you receive back the right to use +the code that you have submitted. + +Any developer who wants to contribute and is employed by a company should +either list the employer as the owner of the code, or get +explicit permission from him to sign the copyright assignment. +This is because in many +countries, all work that an employee does whether on company time or in the +employee's free time is considered to be Intellectual Property of the +company. Obtaining official approval or an FLA from the company will avoid +misunderstandings between the employee, the company, and the Bacula +project. A good number of companies have already followed this procedure. + +The Fiduciary License Agreement is posted on the Bacula web site at: +\elink{http://www.bacula.org/FLA-bacula.en.pdf}{http://www.bacula.org/FLA-bacula.en.pdf} + +The instructions for filling out this agreement are also at: +\elink{http://www.bacula.org/?page=fsfe}{http://www.bacula.org/?page=fsfe} + +It should be filled out, then sent to: + +\begin{verbatim} + Free Software Foundation Europe + Freedom Task Force + Sumatrastrasse 25 + 8006 Zürich + Switzerland +\end{verbatim} + +Please note that the above address is different from the officially +registered office mentioned in the document. When you send in such a +complete document, please notify me: kern at sibbald dot com. + + + +\section{The Development Cycle} +\index{Developement Cycle} +\index{Cycle!Developement} +\addcontentsline{toc}{subsubsection}{Development Cycle} + +As I noted in the 1.38 ReleaseNotes, version 1.38 was different from prior +versions because it had a lot more contributions. I expect that this trend +will continue. As a consequence, I am going to modify how I normally do +development, and instead of making a list of all the features that I will +implement in the next version, I will personally sign up for one (maybe +two) projects at a time, and when they are complete, I will release a new +version. + +The difference is that I will have more time to review the new code that is +being contributed, and will be able to devote more time to a smaller number +of projects (1.38 had too many new features for me to handle correctly). + +I expect that future release schedules will be much the same, and the +number of new features will also be much the same providing that the +contributions continue to come -- and they show no signs of let up :-) + +\index{Feature Requests} +{\bf Feature Requests:} \\ +In addition, I would like to "formalize" the feature requests a bit. + +Instead of me maintaining an informal list of everything I run into +(kernstodo), I would like to maintain a "formal" list of projects. This +means that all new feature requests, including those recently discussed on +the email lists, must be formally submitted and approved. + +Formal submission of feature requests will take two forms: \\ +1. non-mandatory, but highly recommended is to discuss proposed new features +on the mailing list.\\ +2. Formal submission of an Feature Request in a special format. +I'll give an example of this below, but you can also find it on the web +site under "Support -\gt{} Feature Requests". Since it takes a bit of time to +properly fill out a Feature Request form, you probably should check on the email list +first. + +Once the Feature Request is received by the keeper of the projects list, it +will be sent to me, and I will either accept it, send it back +asking for clarification, send it to the email list asking for opinions, or +reject it. + +If it is accepted, it will go in the "projects" file (a simple ASCII file) +maintained in the main Bacula source directory. + +{\bf Implementation of Feature Requests:}\\ +Any qualified developer can sign up for a project. The project must have +an entry in the projects file, and the developer's name will appear in the +Status field. + +{\bf How Feature Requests are accepted:}\\ +Acceptance of Feature Requests depends on several things: \\ +1. feedback from users. If it is negative, the Feature Request will probably not be +accepted. \\ +2. the difficulty of the project. A project that is so +difficult that I cannot imagine finding someone to implement probably won't +be accepted. \\ + 3. whether or not the Feature Request fits within the +current stategy of Bacula (for example an Feature Request that requests changing the +tape to tar format would not be accepted, ...) + +{\bf How Feature Requests are prioritized:}\\ +Once an Feature Request is accepted, it needs to be implemented. If you +can find a developer for it, or one signs up for implementing it, then the +Feature Request becomes top priority (at least for that developer). + +Between releases of Bacula, we will generally solicit Feature Request input +for the next version, and by way of this email, we suggest that you send +discuss and send in your Feature Requests for the next release. Please +verify that the Feature Request is not in the current list (attached to this email). + +Once users have had several weeks to submit Feature Requests, the keeper of the +projects list will +organize them, and request users to vote on them. This will allow fixing +prioritizing the Feature Requests. Having a priority is one thing, but +getting it implement is another thing -- we are hoping that the Bacula +community will take more responsibility for assuring the implementation of +accepted Feature Requests. + +Feature Request format: +\begin{verbatim} +============= Empty Feature Request form =========== +Item n: One line summary ... + Date: Date submitted + Origin: Name and email of originator. + Status: + + What: More detailed explanation ... + + Why: Why it is important ... + + Notes: Additional notes or features (omit if not used) +============== End Feature Request form ============== +\end{verbatim} + +\begin{verbatim} +============= Example Completed Feature Request form =========== +Item 1: Implement a Migration job type that will move the job + data from one device to another. + Origin: Sponsored by Riege Sofware International GmbH. Contact: + Daniel Holtkamp + Date: 28 October 2005 + Status: Partially coded in 1.37 -- much more to do. Assigned to + Kern. + + What: The ability to copy, move, or archive data that is on a + device to another device is very important. + + Why: An ISP might want to backup to disk, but after 30 days + migrate the data to tape backup and delete it from + disk. Bacula should be able to handle this + automatically. It needs to know what was put where, + and when, and what to migrate -- it is a bit like + retention periods. Doing so would allow space to be + freed up for current backups while maintaining older + data on tape drives. + + Notes: Migration could be triggered by: + Number of Jobs + Number of Volumes + Age of Jobs + Highwater size (keep total size) + Lowwater mark +================================================= +\end{verbatim} + + +\section{Bacula Code Submissions and Projects} +\index{Submissions and Projects} +\addcontentsline{toc}{subsection}{Code Submissions and Projects} + +Getting code implemented in Bacula works roughly as follows: + +\begin{itemize} + +\item Kern is the project manager, but prefers not to be a "gate keeper". + This means that the developers are expected to be self-motivated, + and once they have experience submit directly to the SVN. However, + it is a good idea to have your patches reviewed prior to submitting, + and it is a bad idea to submit monster patches because no one will + be able to properly review them. See below for more details on this. + +\item There are growing numbers of contributions (very good). + +\item Some contributions come in the form of relatively small patches, + which Kern reviews, integrates, documents, tests, and maintains. + +\item All Bacula developers take full + responsibility for writing the code, posting as patches so that I can + review it as time permits, integrating it at an appropriate time, + responding to my requests for tweaking it (name changes, ...), + document it in the code, document it in the manual (even though + their mother tongue is not English), test it, develop and commit + regression scripts, and answer in a timely fashion all bug reports -- + even occassionally accepting additional bugs :-) + + This is a sustainable way of going forward with Bacula, and the + direction that the project will be taking more and more. For + example, in the past, we have had some very dedicated programmers + who did major projects. However, these + programmers due to outside obligations (job responsibilities change of + job, school duties, ...) could not continue to maintain the code. In + those cases, the code suffers from lack of maintenance, sometimes I + patch it, sometimes not. In the end, the code gets dropped from the + project (there are two such contributions that are heading in that + direction). When ever possible, we would like to avoid this, and + ensure a continuation of the code and a sharing of the development, + debugging, documentation, and maintenance responsibilities. +\end{itemize} + +\section{Patches for Released Versions} +\index{Patches for Released Versions} +\addcontentsline{toc}{subsection}{Patches for Released Versions} +If you fix a bug in a released version, you should, unless it is +an absolutely trivial bug, create and release a patch file for the +bug. The procedure is as follows: + +Fix the bug in the branch and in the trunk. + +Make a patch file for the branch and add the branch patch to +the patches directory in both the branch and the trunk. +The name should be 2.2.4-xxx.patch where xxx is unique, in this case it can +be "restore", e.g. 2.2.4-restore.patch. Add to the top of the +file a brief description and instructions for applying it -- see for example +2.2.4-poll-mount.patch. The best way to create the patch file is as +follows: + +\begin{verbatim} + (edit) 2.2.4-restore.patch + (input description) + (end edit) + + svn diff >>2.2.4-restore.patch +\end{verbatim} + +check to make sure no extra junk got put into the patch file (i.e. +it should have the patch for that bug only). + +If there is not a bug report on the problem, create one, then add the +patch to the bug report. + +Uthen upload it to the 2.2.x release of bacula-patches. + +So, end the end, the patch file is: +\begin{itemize} +\item Attached to the bug report + +\item In Branch-2.2/bacula/patches/... + +\item In the trunk + +\item Loaded on Source Forge bacula-patches 2.2.x release. When + you add it, click on the check box to send an Email so that all the + users that are monitoring SF patches get notified. +\end{itemize} + + + +\section{SVN Usage} +\index{SVN Usage} +\addcontentsline{toc}{subsection}{SVN Usage} + +Please note that if you are familar with CVS, SVN is very +similar (and better), but there can be a few surprising +differences. + +The *entire* Bacula SourceForge.net Subversion repository can be +checked out through SVN with the following command: + +\begin{verbatim} +svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula bacula +\end{verbatim} + +With the above command, you will get everything, which is a very large +amount of data: + +\begin{verbatim} +branches/ + Branch-1.32a/ + ... + Branch-2.0/ + import/ + vendor/ +tags/ + Release-1.1/ + ... + Release-2.0.2/ +trunk/ + bacula/ + docs/ + gui/ + regress/ + rescue/ +\end{verbatim} + +Note, you should NEVER commit code to any checkout that you have +done of a tag. All tags (e.g. Release-1.1, ... Release-2.0.2) +should be considered read-only. + +You may commit code to the most recent item in +branches (in the above the most recent one is Branch-2.0). If +you want to commit code to an older branch, then please contact +Kern first. + +You may create your own tags and/or branches, but they should +have a name clearly distinctive from Branch-, Release-, or Beta-, +which are official names used by the project. If you create a +tag, then you should NEVER commit code to it, for the same +reason noted above -- it should serve as a marker for something +you released. If you create a branch, then you are free to +commit to it as you wish. + +You may, of course, commit to the trunk. + +In summary: + +\begin{verbatim} +branches + Branch-nnn +tags + Release-nnn + Beta-nnn +\end{verbatim} + +are reserved names to be created only by the project manager (or +with his OK), where the nnn is any sequence of numbers and +periods (e.g. 2.0, 2.0.1, ...). + +In addition all tags even those that you create are read-only +forever. Typically tags represent release points either in the +trunc or in a branch. + + +Coming back to getting source code. +If you only want the current Bacula source code, you could use: + +\begin{verbatim} +svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula bacula +\end{verbatim} + +To view what is in the SVN, point your browser at the following URL: +http://bacula.svn.sourceforge.net/viewvc/bacula/ + +Many of the Subversion (svn) commands are almost identical to those that +you have used for cvs, but some (such as a checkout) can have surprising +results, so you should take a careful look at the documentation. + +Robert has kindly provided the following documentation on the new +svn repository and how to use it: + +Here is the list of branches: +\begin{verbatim} + Branch-1.32a + Branch-1.32e + Branch-1.34.2 + Branch-1.34.5 + Branch-1.36 + Branch-1.36.1 + Branch-1.36.2 + Branch-1.38 + Branch-2.0 + import + vendor +\end{verbatim} + +The list of tags is: +\begin{verbatim} + Release-1.1 Release-1.19 Release-1.19a Release-1.19b + Release-1.20 Release-1.21 Release-1.22 Release-1.23 + Release-1.23a Release-1.24 Release-1.25 Release-1.25a + Release-1.26 Release-1.27 Release-1.27a Release-1.27b + Release-1.27c Release-1.28 Release-1.29 Release-1.30 + Release-1.31 Release-1.31a Release-1.32 Release-1.32a + Release-1.32b Release-1.32c Release-1.32d Release-1.32e + Release-1.32f Release-1.32f-2 Release-1.32f-3 Release-1.32f-4 + Release-1.32f-5 Release-1.34.0 Release-1.34.1 Release-1.34.3 + Release-1.34.4 Release-1.34.5 Release-1.34.6 Release-1.35.1 + Release-1.35.2 Release-1.35.3 Release-1.35.6 Release-1.35.7 + Release-1.35.8 Release-1.36.0 Release-1.36.1 Release-1.36.2 + Release-1.36.3 Release-1.38.0 Release-1.38.1 Release-1.38.10 + Release-1.38.11 Release-1.38.2 Release-1.38.3 Release-1.38.4 + Release-1.38.5 Release-1.38.6 Release-1.38.7 Release-1.38.8 + Release-1.38.9 Release-1.8.1 Release-1.8.2 Release-1.8.3 + Release-1.8.4 Release-1.8.5 Release-1.8.6 Release-2.0.0 + Release-2.0.1 Release-2.0.2 +\end{verbatim} + +Here is a list of commands to get you started. The recommended book is +"Version Control with Subversion", by Ben Collins-Sussmann, +Brian W. Fitzpatrick, and Michael Pilato, O'Reilly. The book is +Open Source, so it is also available on line at: + +\begin{verbatim} + http://svnbook.red-bean.com +\end{verbatim} + +Get a list of commands + +\begin{verbatim} + svn help +\end{verbatim} + +Get a help with a command + +\begin{verbatim} + svn help command +\end{verbatim} + +Checkout the HEAD revision of all modules from the project into the +directory bacula-new + +\begin{verbatim} + svn co https://bacula.svn.sourceforge.net/svnroot/bacula/trunk bacula.new +\end{verbatim} + +Checkout the HEAD revision of the bacula module into the bacula subdirectory + +\begin{verbatim} + svn checkout https://bacula.svn.sourceforge.net/svnroot/bacula/trunk/bacula +\end{verbatim} + +See which files have changed in the working copy + +\begin{verbatim} + svn status +\end{verbatim} + +See which files are out of date + +\begin{verbatim} + svn status -u +\end{verbatim} + +Add a new file file.c + +\begin{verbatim} + svn add file.c +\end{verbatim} + +Create a new directory + +\begin{verbatim} + svn mkdir newdir +\end{verbatim} + +Delete an obsolete file + +\begin{verbatim} + svn delete file.c +\end{verbatim} + +Rename a file + +\begin{verbatim} + svn move file.c newfile.c +\end{verbatim} + +Move a file to a new location + +\begin{verbatim} + svn move file.c ../newdir/file.c +\end{verbatim} + +Copy a file retaining the original history in the new file + +\begin{verbatim} + svn copy file.c newfile.c +\end{verbatim} + +Update the working copy with the outstanding changes + +\begin{verbatim} + svn update +\end{verbatim} + +Compare working copy with the repository + +\begin{verbatim} + svn diff file.c +\end{verbatim} + +Commit the changes in the local working copy + +\begin{verbatim} + svn commit +\end{verbatim} + +Specify which files are ignored in the current directory + +\begin{verbatim} + svn propedit svn:ignore . +\end{verbatim} + +Mark a file to be executable + +\begin{verbatim} + svn propset svn:executable '*' prog.sh +\end{verbatim} + +Unmark a file as executable + +\begin{verbatim} + svn propdel svn:executable prog.sh +\end{verbatim} + +List a file's properties + +\begin{verbatim} + svn proplist file.c +\end{verbatim} + +Create a branch for a new version + +\begin{verbatim} + svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/trunk \ + https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 +\end{verbatim} + +Tag a version for a new release + +\begin{verbatim} + svn copy https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Branch-2.1 \ + https://bacula.svn.sourceforge.net/svnroot/bacula/branches/Release-2.1 +\end{verbatim} + + +Let's say you are working in the directory scripts. You would then do: + +\begin{verbatim} +cd scripts +(edit some files) +\end{verbatim} + +when you are happy with your changes, you can do the following: + +\begin{verbatim} +cd bacula (to your top level directory) +svn diff my-changes.patch +\end{verbatim} + +When the command is done, you can look in the file my-changes.patch +and you will see all the changes you have made to your copy of the +repository. Make sure that you understand all the changes that +it reports before proceeding. If you modified files that you do +do not want to commit to the main repository, you can simply delete +them from your local directory, and they will be restored from the +repository with the "svn update" that is shown below. Normally, you +should not find changes to files that you do not want to commit, and +if you find yourself in that position a lot, you are probably doing +something wrong. + +Let's assume that now you want to commit your changes to the main +SVN repository. + +First do: + +\begin{verbatim} +cd bacula +svn update +\end{verbatim} + +When you do this, it will pull any changes made by other developers into +your local copy of the repository, and it will check for conflicts. If there +are any, it will tell you, and you will need to resolve them. The problems +of resolving conflicts are a bit more than this document can cover, but +you can examine the files it claims have conflicts and look for \lt{}\lt{}\lt{}\lt{} +or look in the .rej files that it creates. If you have problems, just ask +on the developer's list. + +Note, doing the above "svn update" is not absolutely necessary. There are +times when you may be working on code and you want to commit it, but you +explicitly do not want to move up to the latest version of the code in +the SVN. If that is the case, you can simply skip the "svn update" and +do the commit shown below. If the commit fails because of a conflict, it +will tell you, and you must resolve the conflict before it will permit +you to do the commit. + +Once your local copy of the repository has been updated, you can now +commit your changes: + +\begin{verbatim} +svn commit -m "Some comment about what you changed" +\end{verbatim} + +or if you really only want to commit a single file, you can +do: + +\begin{verbatim} +svn commit -m "comment" scripts/file-I-edited +\end{verbatim} + +Note, if you have done a build in your directory, or you have added +other new files, the commit will update only the files that are +actually in the repository. For example, none of the object files +are stored in the repository, so when you do a commit, those object +files will simply be ignored. + +If you want to add new files or remove files from the main SVN +repository, and you are not experienced with SVN, please ask Kern +to do it. If you follow the simple steps above, it is unlikely that +you will do any damage to the repository, and if you do, it is always +possible for us to recover, but it can be painful. + +If you are only working in one subdirectory of say the bacula project, +for example, the scripts directory, you can do your commit from +that subdirectory, and only the changes in that directory and all its +subdirectories will be committed. This can be helpful for translators. +If you are doing a French translation, you will be working in +docs/manual-fr, and if you are always cd'ed into that directory when +doing your commits, your commit will effect only that directory. As +long as you are careful only to change files that you want changed, +you have little to worry about. + +\section{Subversion Resources} +\index{Subversion (svn) Resources} +\addcontentsline{toc}{subsection}{Subversion Resources} + +\begin{verbatim} +cvs2svn Statistics: +------------------ +Total CVS Files: 3286 +Total CVS Revisions: 28924 +Total Unique Tags: 63 +Total Unique Branches: 11 +CVS Repos Size in KB: 232421 +Total SVN Commits: 4116 +First Revision Date: Tue Apr 23 12:42:57 2002 +Last Revision Date: Tue Feb 6 06:37:57 2007 +\end{verbatim} + +The new Subversion repository size on Robert's machine: + +\begin{verbatim} +4.0K bacula-tst/dav +12K bacula-tst/locks +40K bacula-tst/hooks +16K bacula-tst/conf +190M bacula-tst/db/revs +17M bacula-tst/db/revprops +4.0K bacula-tst/db/transactions +206M bacula-tst/db +206M bacula-tst +\end{verbatim} + + +Main Subversion Web Page +\elink{http://subversion.tigris.org}{http://subversion.tigris.org} + +Subversion Book +\elink{http://svnbook.red-bean.com}{http://svnbook.red-bean.com} + +Subversion Clients +\elink{http://subversion.tigris.org/project\_packages.html}{http://subversion.tigris.org/project\_packages.html} + + (For Windows users the TortoiseSVN package is awesome) + +GUI UNIX client link +\elink{http://rapidsvn.tigris.org/}{http://rapidsvn.tigris.org/} + +A nice KDE GUI client: +kdesvn + + + +\section{Developing Bacula} +\index{Developing Bacula} +\index{Bacula!Developing} +\addcontentsline{toc}{subsubsection}{Developing Bacula} + +Typically the simplest way to develop Bacula is to open one xterm window +pointing to the source directory you wish to update; a second xterm window at +the top source directory level, and a third xterm window at the bacula +directory \lt{}top\gt{}/src/bacula. After making source changes in one of the +directories, in the top source directory xterm, build the source, and start +the daemons by entering: + +make and + +./startit then in the enter: + +./console or + +./gnome-console to start the Console program. Enter any commands for testing. +For example: run kernsverify full. + +Note, the instructions here to use {\bf ./startit} are different from using a +production system where the administrator starts Bacula by entering {\bf +./bacula start}. This difference allows a development version of {\bf Bacula} +to be run on a computer at the same time that a production system is running. +The {\bf ./startit} strip starts {\bf Bacula} using a different set of +configuration files, and thus permits avoiding conflicts with any production +system. + +To make additional source changes, exit from the Console program, and in the +top source directory, stop the daemons by entering: + +./stopit then repeat the process. + +\subsection{Debugging} +\index{Debugging} +\addcontentsline{toc}{subsubsection}{Debugging} + +Probably the first thing to do is to turn on debug output. + +A good place to start is with a debug level of 20 as in {\bf ./startit -d20}. +The startit command starts all the daemons with the same debug level. +Alternatively, you can start the appropriate daemon with the debug level you +want. If you really need more info, a debug level of 60 is not bad, and for +just about everything a level of 200. + +\subsection{Using a Debugger} +\index{Using a Debugger} +\index{Debugger!Using a} +\addcontentsline{toc}{subsubsection}{Using a Debugger} + +If you have a serious problem such as a segmentation fault, it can usually be +found quickly using a good multiple thread debugger such as {\bf gdb}. For +example, suppose you get a segmentation violation in {\bf bacula-dir}. You +might use the following to find the problem: + +\lt{}start the Storage and File daemons\gt{} +cd dird +gdb ./bacula-dir +run -f -s -c ./dird.conf +\lt{}it dies with a segmentation fault\gt{} +where +The {\bf -f} option is specified on the {\bf run} command to inhibit {\bf +dird} from going into the background. You may also want to add the {\bf -s} +option to the run command to disable signals which can potentially interfere +with the debugging. + +As an alternative to using the debugger, each {\bf Bacula} daemon has a built +in back trace feature when a serious error is encountered. It calls the +debugger on itself, produces a back trace, and emails the report to the +developer. For more details on this, please see the chapter in the main Bacula +manual entitled ``What To Do When Bacula Crashes (Kaboom)''. + +\subsection{Memory Leaks} +\index{Leaks!Memory} +\index{Memory Leaks} +\addcontentsline{toc}{subsubsection}{Memory Leaks} + +Because Bacula runs routinely and unattended on client and server machines, it +may run for a long time. As a consequence, from the very beginning, Bacula +uses SmartAlloc to ensure that there are no memory leaks. To make detection of +memory leaks effective, all Bacula code that dynamically allocates memory MUST +have a way to release it. In general when the memory is no longer needed, it +should be immediately released, but in some cases, the memory will be held +during the entire time that Bacula is executing. In that case, there MUST be a +routine that can be called at termination time that releases the memory. In +this way, we will be able to detect memory leaks. Be sure to immediately +correct any and all memory leaks that are printed at the termination of the +daemons. + +\subsection{Special Files} +\index{Files!Special} +\index{Special Files} +\addcontentsline{toc}{subsubsection}{Special Files} + +Kern uses files named 1, 2, ... 9 with any extension as scratch files. Thus +any files with these names are subject to being rudely deleted at any time. + +\subsection{When Implementing Incomplete Code} +\index{Code!When Implementing Incomplete} +\index{When Implementing Incomplete Code} +\addcontentsline{toc}{subsubsection}{When Implementing Incomplete Code} + +Please identify all incomplete code with a comment that contains + +\begin{verbatim} +***FIXME*** +\end{verbatim} + +where there are three asterisks (*) before and after the word +FIXME (in capitals) and no intervening spaces. This is important as it allows +new programmers to easily recognize where things are partially implemented. + +\subsection{Bacula Source File Structure} +\index{Structure!Bacula Source File} +\index{Bacula Source File Structure} +\addcontentsline{toc}{subsubsection}{Bacula Source File Structure} + +The distribution generally comes as a tar file of the form {\bf +bacula.x.y.z.tar.gz} where x, y, and z are the version, release, and update +numbers respectively. + +Once you detar this file, you will have a directory structure as follows: + +\footnotesize +\begin{verbatim} +| +Tar file: +|- depkgs + |- mtx (autochanger control program + tape drive info) + |- sqlite (SQLite database program) + +Tar file: +|- depkgs-win32 + |- pthreads (Native win32 pthreads library -- dll) + |- zlib (Native win32 zlib library) + |- wx (wxWidgets source code) + +Project bacula: +|- bacula (main source directory containing configuration + | and installation files) + |- autoconf (automatic configuration files, not normally used + | by users) + |- intl (programs used to translate) + |- platforms (OS specific installation files) + |- redhat (Red Hat installation) + |- solaris (Sun installation) + |- freebsd (FreeBSD installation) + |- irix (Irix installation -- not tested) + |- unknown (Default if system not identified) + |- po (translations of source strings) + |- src (source directory; contains global header files) + |- cats (SQL catalog database interface directory) + |- console (bacula user agent directory) + |- dird (Director daemon) + |- filed (Unix File daemon) + |- win32 (Win32 files to make bacula-fd be a service) + |- findlib (Unix file find library for File daemon) + |- gnome-console (GNOME version of console program) + |- lib (General Bacula library) + |- stored (Storage daemon) + |- tconsole (Tcl/tk console program -- not yet working) + |- testprogs (test programs -- normally only in Kern's tree) + |- tools (Various tool programs) + |- win32 (Native Win32 File daemon) + |- baculafd (Visual Studio project file) + |- compat (compatibility interface library) + |- filed (links to src/filed) + |- findlib (links to src/findlib) + |- lib (links to src/lib) + |- console (beginning of native console program) + |- wx-console (wxWidget console Win32 specific parts) + |- wx-console (wxWidgets console main source program) + +Project regress: +|- regress (Regression scripts) + |- bin (temporary directory to hold Bacula installed binaries) + |- build (temporary directory to hold Bacula source) + |- scripts (scripts and .conf files) + |- tests (test scripts) + |- tmp (temporary directory for temp files) + |- working (temporary working directory for Bacula daemons) + +Project docs: +|- docs (documentation directory) + |- developers (Developer's guide) + |- home-page (Bacula's home page source) + |- manual (html document directory) + |- manual-fr (French translation) + |- manual-de (German translation) + |- techlogs (Technical development notes); + +Project rescue: +|- rescue (Bacula rescue CDROM) + |- linux (Linux rescue CDROM) + |- cdrom (Linux rescue CDROM code) + ... + |- solaris (Solaris rescue -- incomplete) + |- freebsd (FreeBSD rescue -- incomplete) + +Project gui: +|- gui (Bacula GUI projects) + |- bacula-web (Bacula web php management code) + |- bimagemgr (Web application for burning CDROMs) + + +\end{verbatim} +\normalsize + +\subsection{Header Files} +\index{Header Files} +\index{Files!Header} +\addcontentsline{toc}{subsubsection}{Header Files} + +Please carefully follow the scheme defined below as it permits in general only +two header file includes per C file, and thus vastly simplifies programming. +With a large complex project like Bacula, it isn't always easy to ensure that +the right headers are invoked in the right order (there are a few kludges to +make this happen -- i.e. in a few include files because of the chicken and egg +problem, certain references to typedefs had to be replaced with {\bf void} ). + +Every file should include {\bf bacula.h}. It pulls in just about everything, +with very few exceptions. If you have system dependent ifdefing, please do it +in {\bf baconfig.h}. The version number and date are kept in {\bf version.h}. + +Each of the subdirectories (console, cats, dird, filed, findlib, lib, stored, +...) contains a single directory dependent include file generally the name of +the directory, which should be included just after the include of {\bf +bacula.h}. This file (for example, for the dird directory, it is {\bf dird.h}) +contains either definitions of things generally needed in this directory, or +it includes the appropriate header files. It always includes {\bf protos.h}. +See below. + +Each subdirectory contains a header file named {\bf protos.h}, which contains +the prototypes for subroutines exported by files in that directory. {\bf +protos.h} is always included by the main directory dependent include file. + +\subsection{Programming Standards} +\index{Standards!Programming} +\index{Programming Standards} +\addcontentsline{toc}{subsubsection}{Programming Standards} + +For the most part, all code should be written in C unless there is a burning +reason to use C++, and then only the simplest C++ constructs will be used. +Note, Bacula is slowly evolving to use more and more C++. + +Code should have some documentation -- not a lot, but enough so that I can +understand it. Look at the current code, and you will see that I document more +than most, but am definitely not a fanatic. + +I prefer simple linear code where possible. Gotos are strongly discouraged +except for handling an error to either bail out or to retry some code, and +such use of gotos can vastly simplify the program. + +Remember this is a C program that is migrating to a {\bf tiny} subset of C++, +so be conservative in your use of C++ features. + +\subsection{Do Not Use} +\index{Use!Do Not} +\index{Do Not Use} +\addcontentsline{toc}{subsubsection}{Do Not Use} + +\begin{itemize} + \item STL -- it is totally incomprehensible. +\end{itemize} + +\subsection{Avoid if Possible} +\index{Possible!Avoid if} +\index{Avoid if Possible} +\addcontentsline{toc}{subsubsection}{Avoid if Possible} + +\begin{itemize} +\item Using {\bf void *} because this generally means that one must + using casting, and in C++ casting is rather ugly. It is OK to use + void * to pass structure address where the structure is not known + to the routines accepting the packet (typically callback routines). + However, declaring "void *buf" is a bad idea. Please use the + correct types whenever possible. + +\item Using undefined storage specifications such as (short, int, long, + long long, size\_t ...). The problem with all these is that the number of bytes + they allocate depends on the compiler and the system. Instead use + Bacula's types (int8\_t, uint8\_t, int32\_t, uint32\_t, int64\_t, and + uint64\_t). This guarantees that the variables are given exactly the + size you want. Please try at all possible to avoid using size\_t ssize\_t + and the such. They are very system dependent. However, some system + routines may need them, so their use is often unavoidable. + +\item Returning a malloc'ed buffer from a subroutine -- someone will forget + to release it. + +\item Heap allocation (malloc) unless needed -- it is expensive. Use + POOL\_MEM instead. + +\item Templates -- they can create portability problems. + +\item Fancy or tricky C or C++ code, unless you give a good explanation of + why you used it. + +\item Too much inheritance -- it can complicate the code, and make reading it + difficult (unless you are in love with colons) + +\end{itemize} + +\subsection{Do Use Whenever Possible} +\index{Possible!Do Use Whenever} +\index{Do Use Whenever Possible} +\addcontentsline{toc}{subsubsection}{Do Use Whenever Possible} + +\begin{itemize} +\item Locking and unlocking within a single subroutine. + +\item A single point of exit from all subroutines. A goto is + perfectly OK to use to get out early, but only to a label + named bail\_out, and possibly an ok\_out. See current code + examples. + +\item Malloc and free within a single subroutine. + +\item Comments and global explanations on what your code or algorithm does. + +\end{itemize} + +\subsection{Indenting Standards} +\index{Standards!Indenting} +\index{Indenting Standards} +\addcontentsline{toc}{subsubsection}{Indenting Standards} + +I cannot stand code indented 8 columns at a time. This makes the code +unreadable. Even 4 at a time uses a lot of space, so I have adopted indenting +3 spaces at every level. Note, indention is the visual appearance of the +source on the page, while tabbing is replacing a series of up to 8 spaces from +a tab character. + +The closest set of parameters for the Linux {\bf indent} program that will +produce reasonably indented code are: + +\footnotesize +\begin{verbatim} +-nbad -bap -bbo -nbc -br -brs -c36 -cd36 -ncdb -ce -ci3 -cli0 +-cp36 -d0 -di1 -ndj -nfc1 -nfca -hnl -i3 -ip0 -l85 -lp -npcs +-nprs -npsl -saf -sai -saw -nsob -nss -nbc -ncs -nbfda +\end{verbatim} +\normalsize + +You can put the above in your .indent.pro file, and then just invoke indent on +your file. However, be warned. This does not produce perfect indenting, and it +will mess up C++ class statements pretty badly. + +Braces are required in all if statements (missing in some very old code). To +avoid generating too many lines, the first brace appears on the first line +(e.g. of an if), and the closing brace is on a line by itself. E.g. + +\footnotesize +\begin{verbatim} + if (abc) { + some_code; + } +\end{verbatim} +\normalsize + +Just follow the convention in the code. Originally I indented case clauses +under a switch(), but now I prefer non-indented cases. + +\footnotesize +\begin{verbatim} + switch (code) { + case 'A': + do something + break; + case 'B': + again(); + break; + default: + break; + } +\end{verbatim} +\normalsize + +Avoid using // style comments except for temporary code or turning off debug +code. Standard C comments are preferred (this also keeps the code closer to +C). + +Attempt to keep all lines less than 85 characters long so that the whole line +of code is readable at one time. This is not a rigid requirement. + +Always put a brief description at the top of any new file created describing +what it does and including your name and the date it was first written. Please +don't forget any Copyrights and acknowledgments if it isn't 100\% your code. +Also, include the Bacula copyright notice that is in {\bf src/c}. + +In general you should have two includes at the top of the an include for the +particular directory the code is in, for includes are needed, but this should +be rare. + +In general (except for self-contained packages), prototypes should all be put +in {\bf protos.h} in each directory. + +Always put space around assignment and comparison operators. + +\footnotesize +\begin{verbatim} + a = 1; + if (b >= 2) { + cleanup(); + } +\end{verbatim} +\normalsize + +but your can compress things in a {\bf for} statement: + +\footnotesize +\begin{verbatim} + for (i=0; i < del.num_ids; i++) { + ... +\end{verbatim} +\normalsize + +Don't overuse the inline if (?:). A full {\bf if} is preferred, except in a +print statement, e.g.: + +\footnotesize +\begin{verbatim} + if (ua->verbose \&& del.num_del != 0) { + bsendmsg(ua, _("Pruned %d %s on Volume %s from catalog.\n"), del.num_del, + del.num_del == 1 ? "Job" : "Jobs", mr->VolumeName); + } +\end{verbatim} +\normalsize + +Leave a certain amount of debug code (Dmsg) in code you submit, so that future +problems can be identified. This is particularly true for complicated code +likely to break. However, try to keep the debug code to a minimum to avoid +bloating the program and above all to keep the code readable. + +Please keep the same style in all new code you develop. If you include code +previously written, you have the option of leaving it with the old indenting +or re-indenting it. If the old code is indented with 8 spaces, then please +re-indent it to Bacula standards. + +If you are using {\bf vim}, simply set your tabstop to 8 and your shiftwidth +to 3. + +\subsection{Tabbing} +\index{Tabbing} +\addcontentsline{toc}{subsubsection}{Tabbing} + +Tabbing (inserting the tab character in place of spaces) is as normal on all +Unix systems -- a tab is converted space up to the next column multiple of 8. +My editor converts strings of spaces to tabs automatically -- this results in +significant compression of the files. Thus, you can remove tabs by replacing +them with spaces if you wish. Please don't confuse tabbing (use of tab +characters) with indenting (visual alignment of the code). + +\subsection{Don'ts} +\index{Don'ts} +\addcontentsline{toc}{subsubsection}{Don'ts} + +Please don't use: + +\footnotesize +\begin{verbatim} +strcpy() +strcat() +strncpy() +strncat(); +sprintf() +snprintf() +\end{verbatim} +\normalsize + +They are system dependent and un-safe. These should be replaced by the Bacula +safe equivalents: + +\footnotesize +\begin{verbatim} +char *bstrncpy(char *dest, char *source, int dest_size); +char *bstrncat(char *dest, char *source, int dest_size); +int bsnprintf(char *buf, int32_t buf_len, const char *fmt, ...); +int bvsnprintf(char *str, int32_t size, const char *format, va_list ap); +\end{verbatim} +\normalsize + +See src/lib/bsys.c for more details on these routines. + +Don't use the {\bf \%lld} or the {\bf \%q} printf format editing types to edit +64 bit integers -- they are not portable. Instead, use {\bf \%s} with {\bf +edit\_uint64()}. For example: + +\footnotesize +\begin{verbatim} + char buf[100]; + uint64_t num = something; + char ed1[50]; + bsnprintf(buf, sizeof(buf), "Num=%s\n", edit_uint64(num, ed1)); +\end{verbatim} +\normalsize + +The edit buffer {\bf ed1} must be at least 27 bytes long to avoid overflow. +See src/lib/edit.c for more details. If you look at the code, don't start +screaming that I use {\bf lld}. I actually use subtle trick taught to me by +John Walker. The {\bf lld} that appears in the editing routine is actually +{\bf \#define} to a what is needed on your OS (usually ``lld'' or ``q'') and +is defined in autoconf/configure.in for each OS. C string concatenation causes +the appropriate string to be concatenated to the ``\%''. + +Also please don't use the STL or Templates or any complicated C++ code. + +\subsection{Message Classes} +\index{Classes!Message} +\index{Message Classes} +\addcontentsline{toc}{subsubsection}{Message Classes} + +Currently, there are five classes of messages: Debug, Error, Job, Memory, +and Queued. + +\subsection{Debug Messages} +\index{Messages!Debug} +\index{Debug Messages} +\addcontentsline{toc}{subsubsection}{Debug Messages} + +Debug messages are designed to be turned on at a specified debug level and are +always sent to STDOUT. There are designed to only be used in the development +debug process. They are coded as: + +DmsgN(level, message, arg1, ...) where the N is a number indicating how many +arguments are to be substituted into the message (i.e. it is a count of the +number arguments you have in your message -- generally the number of percent +signs (\%)). {\bf level} is the debug level at which you wish the message to +be printed. message is the debug message to be printed, and arg1, ... are the +arguments to be substituted. Since not all compilers support \#defines with +varargs, you must explicitly specify how many arguments you have. + +When the debug message is printed, it will automatically be prefixed by the +name of the daemon which is running, the filename where the Dmsg is, and the +line number within the file. + +Some actual examples are: + +Dmsg2(20, ``MD5len=\%d MD5=\%s\textbackslash{}n'', strlen(buf), buf); + +Dmsg1(9, ``Created client \%s record\textbackslash{}n'', client->hdr.name); + +\subsection{Error Messages} +\index{Messages!Error} +\index{Error Messages} +\addcontentsline{toc}{subsubsection}{Error Messages} + +Error messages are messages that are related to the daemon as a whole rather +than a particular job. For example, an out of memory condition my generate an +error message. They should be very rarely needed. In general, you should be +using Job and Job Queued messages (Jmsg and Qmsg). They are coded as: + +EmsgN(error-code, level, message, arg1, ...) As with debug messages, you must +explicitly code the of arguments to be substituted in the message. error-code +indicates the severity or class of error, and it may be one of the following: + +\addcontentsline{lot}{table}{Message Error Code Classes} +\begin{longtable}{lp{3in}} +{{\bf M\_ABORT} } & {Causes the daemon to immediately abort. This should be +used only in extreme cases. It attempts to produce a traceback. } \\ +{{\bf M\_ERROR\_TERM} } & {Causes the daemon to immediately terminate. This +should be used only in extreme cases. It does not produce a traceback. } \\ +{{\bf M\_FATAL} } & {Causes the daemon to terminate the current job, but the +daemon keeps running } \\ +{{\bf M\_ERROR} } & {Reports the error. The daemon and the job continue +running } \\ +{{\bf M\_WARNING} } & {Reports an warning message. The daemon and the job +continue running } \\ +{{\bf M\_INFO} } & {Reports an informational message.} + +\end{longtable} + +There are other error message classes, but they are in a state of being +redesigned or deprecated, so please do not use them. Some actual examples are: + + +Emsg1(M\_ABORT, 0, ``Cannot create message thread: \%s\textbackslash{}n'', +strerror(status)); + +Emsg3(M\_WARNING, 0, ``Connect to File daemon \%s at \%s:\%d failed. Retrying +...\textbackslash{}n'', client-\gt{}hdr.name, client-\gt{}address, +client-\gt{}port); + +Emsg3(M\_FATAL, 0, ``bdird\lt{}filed: bad response from Filed to \%s command: +\%d \%s\textbackslash{}n'', cmd, n, strerror(errno)); + +\subsection{Job Messages} +\index{Job Messages} +\index{Messages!Job} +\addcontentsline{toc}{subsubsection}{Job Messages} + +Job messages are messages that pertain to a particular job such as a file that +could not be saved, or the number of files and bytes that were saved. They +Are coded as: +\begin{verbatim} +Jmsg(jcr, M\_FATAL, 0, "Text of message"); +\end{verbatim} +A Jmsg with M\_FATAL will fail the job. The Jmsg() takes varargs so can +have any number of arguments for substituted in a printf like format. +Output from the Jmsg() will go to the Job report. +
+If the Jmsg is followed with a number such as Jmsg1(...), the number +indicates the number of arguments to be substituted (varargs is not +standard for \#defines), and what is more important is that the file and +line number will be prefixed to the message. This permits a sort of debug +from user's output. + +\subsection{Queued Job Messages} +\index{Queued Job Messages} +\index{Messages!Job} +\addcontentsline{toc}{subsubsection}{Queued Job Messages} +Queued Job messages are similar to Jmsg()s except that the message is +Queued rather than immediately dispatched. This is necessary within the +network subroutines and in the message editing routines. This is to prevent +recursive loops, and to ensure that messages can be delivered even in the +event of a network error. + + +\subsection{Memory Messages} +\index{Messages!Memory} +\index{Memory Messages} +\addcontentsline{toc}{subsubsection}{Memory Messages} + +Memory messages are messages that are edited into a memory buffer. Generally +they are used in low level routines such as the low level device file dev.c in +the Storage daemon or in the low level Catalog routines. These routines do not +generally have access to the Job Control Record and so they return error +essages reformatted in a memory buffer. Mmsg() is the way to do this. diff --git a/docs/manuals/fr/developers/index.perl b/docs/manuals/fr/developers/index.perl new file mode 100644 index 00000000..bc4e1b60 --- /dev/null +++ b/docs/manuals/fr/developers/index.perl @@ -0,0 +1,564 @@ +# This module does multiple indices, supporting the style of the LaTex 'index' +# package. + +# Version Information: +# 16-Feb-2005 -- Original Creation. Karl E. Cunningham +# 14-Mar-2005 -- Clarified and Consolodated some of the code. +# Changed to smoothly handle single and multiple indices. + +# Two LaTeX index formats are supported... +# --- SINGLE INDEX --- +# \usepackage{makeidx} +# \makeindex +# \index{entry1} +# \index{entry2} +# \index{entry3} +# ... +# \printindex +# +# --- MULTIPLE INDICES --- +# +# \usepackage{makeidx} +# \usepackage{index} +# \makeindex -- latex2html doesn't care but LaTeX does. +# \newindex{ref1}{ext1}{ext2}{title1} +# \newindex{ref2}{ext1}{ext2}{title2} +# \newindex{ref3}{ext1}{ext2}{title3} +# \index[ref1]{entry1} +# \index[ref1]{entry2} +# \index[ref3]{entry3} +# \index[ref2]{entry4} +# \index{entry5} +# \index[ref3]{entry6} +# ... +# \printindex[ref1] +# \printindex[ref2] +# \printindex[ref3] +# \printindex +# ___________________ +# +# For the multiple-index style, each index is identified by the ref argument to \newindex, \index, +# and \printindex. A default index is allowed, which is indicated by omitting the optional +# argument. The default index does not require a \newindex command. As \index commands +# are encountered, their entries are stored according +# to the ref argument. When the \printindex command is encountered, the stored index +# entries for that argument are retrieved and printed. The title for each index is taken +# from the last argument in the \newindex command. +# While processing \index and \printindex commands, if no argument is given the index entries +# are built into a default index. The title of the default index is simply "Index". +# This makes the difference between single- and multiple-index processing trivial. +# +# Another method can be used by omitting the \printindex command and just using \include to +# pull in index files created by the makeindex program. These files will start with +# \begin{theindex}. This command is used to determine where to print the index. Using this +# approach, the indices will be output in the same order as the newindex commands were +# originally found (see below). Using a combination of \printindex and \include{indexfile} has not +# been tested and may produce undesireable results. +# +# The index data are stored in a hash for later sorting and output. As \printindex +# commands are handled, the order in which they were found in the tex filea is saved, +# associated with the ref argument to \printindex. +# +# We use the original %index hash to store the index data into. We append a \002 followed by the +# name of the index to isolate the entries in different indices from each other. This is necessary +# so that different indices can have entries with the same name. For the default index, the \002 is +# appended without the name. +# +# Since the index order in the output cannot be determined if the \include{indexfile} +# command is used, the order will be assumed from the order in which the \newindex +# commands were originally seen in the TeX files. This order is saved as well as the +# order determined from any printindex{ref} commands. If \printindex commnads are used +# to specify the index output, that order will be used. If the \include{idxfile} command +# is used, the order of the original newindex commands will be used. In this case the +# default index will be printed last since it doesn't have a corresponding \newindex +# command and its order cannot be determined. Mixing \printindex and \include{idxfile} +# commands in the same file is likely to produce less than satisfactory results. +# +# +# The hash containing index data is named %indices. It contains the following data: +#{ +# 'title' => { +# $ref1 => $indextitle , +# $ref2 => $indextitle , +# ... +# }, +# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +#} + + +# Globals to handle multiple indices. +my %indices; + +# This tells the system to use up to 7 words in index entries. +$WORDS_IN_INDEX = 10; + +# KEC 2-18-05 +# Handles the \newindex command. This is called if the \newindex command is +# encountered in the LaTex source. Gets the index ref and title from the arguments. +# Saves the index ref and title. +# Note that we are called once to handle multiple \newindex commands that are +# newline-separated. +sub do_cmd_newindex { + my $data = shift; + # The data is sent to us as fields delimited by their ID #'s. We extract the + # fields. + foreach my $line (split("\n",$data)) { + my @fields = split (/(?:\<\#\d+?\#\>)+/,$line); + + # The index name and title are the second and fourth fields in the data. + if ($line =~ /^ \001 + # @ -> \002 + # | -> \003 + $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines + # protect \001 occurring with images + $str =~ s/\001/\016/g; # 0x1 to 0xF + $str =~ s/\\\\/\011/g; # Double backslash -> 0xB + $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC + $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD + $str =~ s/!/\001/g; # Exclamation point -> 0x1 + $str =~ s/\013/!/g; # 0xD -> Exclaimation point + $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF + $str =~ s/@/\002/g; # At sign -> 0x2 + $str =~ s/\015/@/g; # 0xF to At sign + $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11 + $str =~ s/\|/\003/g; # Vertical line to 0x3 + $str =~ s/\017/|/g; # 0x11 to vertical line + $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is + $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot; + $str =~ s/\011/\\\\/g; # 0x11 to double backslash + local($key_part, $pageref) = split("\003", $str, 2); + + # For any keys of the form: blablabla!blablabla, which want to be split at the + # exclamation point, replace the ! with a comma and a space. We don't do it + # that way for this index. + $key_part =~ s/\001/, /g; + local(@keys) = split("\001", $key_part); + # If TITLE is not yet available use $before. + $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title))); + $TITLE = $before unless $TITLE; + # Save the reference + local($words) = ''; + if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; } + elsif ($SHORT_INDEX) { $words = &make_shortidxname; } + else { $words = &make_idxname; } + local($super_key) = ''; + local($sort_key, $printable_key, $cur_key); + foreach $key (@keys) { + $key =~ s/\016/\001/g; # revert protected \001s + ($sort_key, $printable_key) = split("\002", $key); + # + # RRM: 16 May 1996 + # any \label in the printable-key will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($printable_key =~ /tex2html_anchor_mark/ ) { + $printable_key =~ s/><\/A>$cross_ref_mark/ + $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_label = $external_labels{$label} unless + ($ref_label = $ref_files{$label}); + '"' . "$ref_label#$label" . '">' . + &get_ref_mark($label,$id)} + /geo; + } + $printable_key =~ s/<\#[^\#>]*\#>//go; + #RRM + # recognise \char combinations, for a \backslash + # + $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s + $printable_key =~ s/\&\#;\`
/\\/g; # ditto + $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto + # + # $sort_key .= "@$printable_key" if !($printable_key); # RRM + $sort_key .= "@$printable_key" if !($sort_key); # RRM + $sort_key =~ tr/A-Z/a-z/; + if ($super_key) { + $cur_key = $super_key . "\001" . $sort_key; + $sub_index{$super_key} .= $cur_key . "\004"; + } else { + $cur_key = $sort_key; + } + + # Append the $index_name to the current key with a \002 delimiter. This will + # allow the same index entry to appear in more than one index. + $index_key = $cur_key . "\002$index_name"; + + $index{$index_key} .= ""; + + # + # RRM, 15 June 1996 + # if there is no printable key, but one is known from + # a previous index-entry, then use it. + # + if (!($printable_key) && ($printable_key{$index_key})) + { $printable_key = $printable_key{$index_key}; } +# if (!($printable_key) && ($printable_key{$cur_key})) +# { $printable_key = $printable_key{$cur_key}; } + # + # do not overwrite the printable_key if it contains an anchor + # + if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ )) + { $printable_key{$index_key} = $printable_key || $key; } +# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ )) +# { $printable_key{$cur_key} = $printable_key || $key; } + + $super_key = $cur_key; + } + # + # RRM + # page-ranges, from |( and |) and |see + # + if ($pageref) { + if ($pageref eq "\(" ) { + $pageref = ''; + $next .= " from "; + } elsif ($pageref eq "\)" ) { + $pageref = ''; + local($next) = $index{$index_key}; +# local($next) = $index{$cur_key}; + # $next =~ s/[\|] *$//; + $next =~ s/(\n )?\| $//; + $index{$index_key} = "$next to "; +# $index{$cur_key} = "$next to "; + } + } + + if ($pageref) { + $pageref =~ s/\s*$//g; # remove trailing spaces + if (!$pageref) { $pageref = ' ' } + $pageref =~ s/see/see <\/i> /g; + # + # RRM: 27 Dec 1996 + # check if $pageref corresponds to a style command. + # If so, apply it to the $words. + # + local($tmp) = "do_cmd_$pageref"; + if (defined &$tmp) { + $words = &$tmp("<#0#>$words<#0#>"); + $words =~ s/<\#[^\#]*\#>//go; + $pageref = ''; + } + } + # + # RRM: 25 May 1996 + # any \label in the pageref section will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($pageref) { + if ($pageref =~ /tex2html_anchor_mark/ ) { + $pageref =~ s/><\/A>$cross_ref_mark/ + $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_files{$label} = ''; # ???? RRM + if ($index_labels{$label}) { $ref_label = ''; } + else { $ref_label = $external_labels{$label} + unless ($ref_label = $ref_files{$label}); + } + '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo; + } + $pageref =~ s/<\#[^\#>]*\#>//go; + + if ($pageref eq ' ') { $index{$index_key}='@'; } + else { $index{$index_key} .= $pageref . "\n | "; } + } else { + local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words); + $thisref =~ s/\n//g; + $index{$index_key} .= $thisref."\n | "; + } + #print "\nREF: $sort_key : $index_key :$index{$index_key}"; + + #join('',"$anchor_invisible_mark<\/A>",$_); + + "$anchor_invisible_mark<\/A>"; +} + + +# KEC. -- Copied from makeidx.perl, then modified to do multiple indices. +# Feeds the index entries to the output. This is called for each index to be built. +# +# Generates a list of lookup keys for index entries, from both %printable_keys +# and %index keys. +# Sorts the keys according to index-sorting rules. +# Removes keys with a 0x01 token. (duplicates?) +# Builds a string to go to the index file. +# Adds the index entries to the string if they belong in this index. +# Keeps track of which index is being worked on, so only the proper entries +# are included. +# Places the index just built in to the output at the proper place. +{ my $index_number = 0; +sub add_real_idx { + print "\nDoing the index ... Index Number $index_number\n"; + local($key, @keys, $next, $index, $old_key, $old_html); + my ($idx_ref,$keyref); + # RRM, 15.6.96: index constructed from %printable_key, not %index + @keys = keys %printable_key; + + while (/$idx_mark/) { + # Get the index reference from what follows the $idx_mark and + # remove it from the string. + s/$idxmark\002(.*?)\002/$idxmark/; + $idx_ref = $1; + $index = ''; + # include non- makeidx index-entries + foreach $key (keys %index) { + next if $printable_key{$key}; + $old_key = $key; + if ($key =~ s/###(.*)$//) { + next if $printable_key{$key}; + push (@keys, $key); + $printable_key{$key} = $key; + if ($index{$old_key} =~ /HREF="([^"]*)"/i) { + $old_html = $1; + $old_html =~ /$dd?([^#\Q$dd\E]*)#/; + $old_html = $1; + } else { $old_html = '' } + $index{$key} = $index{$old_key} . $old_html."\n | "; + }; + } + @keys = sort makeidx_keysort @keys; + @keys = grep(!/\001/, @keys); + my $cnt = 0; + foreach $key (@keys) { + my ($keyref) = $key =~ /.*\002(.*)/; + next unless ($idx_ref eq $keyref); # KEC. + $index .= &add_idx_key($key); + $cnt++; + } + print "$cnt Index Entries Added\n"; + $index = '
'.$index unless ($index =~ /^\s*/); + $index_number++; # KEC. + if ($SHORT_INDEX) { + print "(compact version with Legend)"; + local($num) = ( $index =~ s/\ 50 ) { + s/$idx_mark/$preindex
\n$index\n<\/DL>$preindex/o; + } else { + s/$idx_mark/$preindex
\n$index\n<\/DL>/o; + } + } else { + s/$idx_mark/
\n$index\n<\/DL>/o; } + } +} +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# The bibliography and the index should be treated as separate sections +# in their own HTML files. The \bibliography{} command acts as a sectioning command +# that has the desired effect. But when the bibliography is constructed +# manually using the thebibliography environment, or when using the +# theindex environment it is not possible to use the normal sectioning +# mechanism. This subroutine inserts a \bibliography{} or a dummy +# \textohtmlindex command just before the appropriate environments +# to force sectioning. +sub add_bbl_and_idx_dummy_commands { + local($id) = $global{'max_id'}; + + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg; + ## if ($bbl_cnt == 1) { + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo; + #} + $global{'max_id'} = $id; + # KEC. Modified to global substitution to place multiple index tokens. + s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go; + # KEC. Modified to pick up the optional argument to \printindex + s/[\\]printindex\s*(\[.*?\])?/ + do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego; + &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands); +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# For each textohtmlindex mark found, determine the index titles and headers. +# We place the index ref in the header so the proper index can be generated later. +# For the default index, the index ref is blank. +# +# One problem is that this routine is called twice.. Once for processing the +# command as originally seen, and once for processing the command when +# doing the name for the index file. We can detect that by looking at the +# id numbers (or ref) surrounding the \theindex command, and not incrementing +# index_number unless a new id (or ref) is seen. This has the side effect of +# having to unconventionally start the index_number at -1. But it works. +# +# Gets the title from the list of indices. +# If this is the first index, save the title in $first_idx_file. This is what's referenced +# in the navigation buttons. +# Increment the index_number for next time. +# If the indexname command is defined or a newcommand defined for indexname, do it. +# Save the index TITLE in the toc +# Save the first_idx_file into the idxfile. This goes into the nav buttons. +# Build index_labels if needed. +# Create the index headings and put them in the output stream. + +{ my $index_number = 0; # Will be incremented before use. + my $first_idx_file; # Static + my $no_increment = 0; + +sub do_cmd_textohtmlindex { + local($_) = @_; + my ($idxref,$idxnum,$index_name); + + # We get called from make_name with the first argument = "\001noincrement". This is a sign + # to not increment $index_number the next time we are called. We get called twice, once + # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name + # but doesn't use the result so we get called a second time by process_command. This works fine + # except for cases where there are multiple indices except if they aren't named, which is the case + # when the index is inserted by an include command in latex. In these cases we are only able to use + # the index number to decide which index to draw from, and we don't know how to increment that index + # number if we get called a variable number of times for the same index, as is the case between + # making html (one output file) and web (multiple output files) output formats. + if (/\001noincrement/) { + $no_increment = 1; + return; + } + + # Remove (but save) the index reference + s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e; + + # If we have an $idxref, the index name was specified. In this case, we have all the + # information we need to carry on. Otherwise, we need to get the idxref + # from the $index_number and set the name to "Index". + if ($idxref) { + $index_name = $indices{'title'}{$idxref}; + } else { + if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) { + $index_name = $indices{'title'}{$idxref}; + } else { + $idxref = ''; + $index_name = "Index"; + } + } + + $idx_title = "Index"; # The name displayed in the nav bar text. + + # Only set $idxfile if we are at the first index. This will point the + # navigation panel to the first index file rather than the last. + $first_idx_file = $CURRENT_FILE if ($index_number == 0); + $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar. + $toc_sec_title = $index_name; # Index link text in the toc. + $TITLE = $toc_sec_title; # Title for this index, from which its filename is built. + if (%index_labels) { &make_index_labels(); } + if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); } + else { $preindex = ''; } + local $idx_head = $section_headings{'textohtmlindex'}; + local($heading) = join('' + , &make_section_heading($TITLE, $idx_head) + , $idx_mark, "\002", $idxref, "\002" ); + local($pre,$post) = &minimize_open_tags($heading); + $index_number++ unless ($no_increment); + $no_increment = 0; + join('',"
\n" , $pre, $_); +} +} + +# Returns an index key, given the key passed as the first argument. +# Not modified for multiple indices. +sub add_idx_key { + local($key) = @_; + local($index, $next); + if (($index{$key} eq '@' )&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { $index .= "

\n
".&print_key."\n
"; } + else { $index .= "

\n
".&print_key."\n
"; } + } elsif (($index{$key})&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { + $next = "
".&print_key."\n : ". &print_idx_links; + } else { + $next = "
".&print_key."\n
". &print_idx_links; + } + $index .= $next."\n"; + $index_printed{$key} = 1; + } + + if ($sub_index{$key}) { + local($subkey, @subkeys, $subnext, $subindex); + @subkeys = sort(split("\004", $sub_index{$key})); + if ($SHORT_INDEX) { + $index .= "
".&print_key unless $index_printed{$key}; + $index .= "
\n"; + } else { + $index .= "
".&print_key."\n
" unless $index_printed{$key}; + $index .= "
\n"; + } + foreach $subkey (@subkeys) { + $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey}); + } + $index .= "
\n"; + } + return $index; +} + +1; # Must be present as the last line. diff --git a/docs/manuals/fr/developers/latex2html-init.pl b/docs/manuals/fr/developers/latex2html-init.pl new file mode 100644 index 00000000..14b5c319 --- /dev/null +++ b/docs/manuals/fr/developers/latex2html-init.pl @@ -0,0 +1,10 @@ +# This file serves as a place to put initialization code and constants to +# affect the behavior of latex2html for generating the bacula manuals. + +# $LINKPOINT specifies what filename to use to link to when creating +# index.html. Not that this is a hard link. +$LINKPOINT='"$OVERALL_TITLE"'; + + +# The following must be the last line of this file. +1; diff --git a/docs/manuals/fr/developers/md5.tex b/docs/manuals/fr/developers/md5.tex new file mode 100644 index 00000000..aed995b4 --- /dev/null +++ b/docs/manuals/fr/developers/md5.tex @@ -0,0 +1,184 @@ +%% +%% + +\chapter{Bacula MD5 Algorithm} +\label{MD5Chapter} +\addcontentsline{toc}{section}{} + +\section{Command Line Message Digest Utility } +\index{Utility!Command Line Message Digest } +\index{Command Line Message Digest Utility } +\addcontentsline{toc}{subsection}{Command Line Message Digest Utility} + + +This page describes {\bf md5}, a command line utility usable on either Unix or +MS-DOS/Windows, which generates and verifies message digests (digital +signatures) using the MD5 algorithm. This program can be useful when +developing shell scripts or Perl programs for software installation, file +comparison, and detection of file corruption and tampering. + +\subsection{Name} +\index{Name} +\addcontentsline{toc}{subsubsection}{Name} + +{\bf md5} - generate / check MD5 message digest + +\subsection{Synopsis} +\index{Synopsis } +\addcontentsline{toc}{subsubsection}{Synopsis} + +{\bf md5} [ {\bf -c}{\it signature} ] [ {\bf -u} ] [ {\bf -d}{\it input\_text} +| {\it infile} ] [ {\it outfile} ] + +\subsection{Description} +\index{Description } +\addcontentsline{toc}{subsubsection}{Description} + +A {\it message digest} is a compact digital signature for an arbitrarily long +stream of binary data. An ideal message digest algorithm would never generate +the same signature for two different sets of input, but achieving such +theoretical perfection would require a message digest as long as the input +file. Practical message digest algorithms compromise in favour of a digital +signature of modest size created with an algorithm designed to make +preparation of input text with a given signature computationally infeasible. +Message digest algorithms have much in common with techniques used in +encryption, but to a different end; verification that data have not been +altered since the signature was published. + +Many older programs requiring digital signatures employed 16 or 32 bit {\it +cyclical redundancy codes} (CRC) originally developed to verify correct +transmission in data communication protocols, but these short codes, while +adequate to detect the kind of transmission errors for which they were +intended, are insufficiently secure for applications such as electronic +commerce and verification of security related software distributions. + +The most commonly used present-day message digest algorithm is the 128 bit MD5 +algorithm, developed by Ron Rivest of the +\elink{MIT}{http://web.mit.edu/} +\elink{Laboratory for Computer Science}{http://www.lcs.mit.edu/} and +\elink{RSA Data Security, Inc.}{http://www.rsa.com/} The algorithm, with a +reference implementation, was published as Internet +\elink{RFC 1321}{http://www.fourmilab.ch/md5/rfc1321.html} in April 1992, and +was placed into the public domain at that time. Message digest algorithms such +as MD5 are not deemed ``encryption technology'' and are not subject to the +export controls some governments impose on other data security products. +(Obviously, the responsibility for obeying the laws in the jurisdiction in +which you reside is entirely your own, but many common Web and Mail utilities +use MD5, and I am unaware of any restrictions on their distribution and use.) + +The MD5 algorithm has been implemented in numerous computer languages +including C, +\elink{Perl}{http://www.perl.org/}, and +\elink{Java}{http://www.javasoft.com/}; if you're writing a program in such a +language, track down a suitable subroutine and incorporate it into your +program. The program described on this page is a {\it command line} +implementation of MD5, intended for use in shell scripts and Perl programs (it +is much faster than computing an MD5 signature directly in Perl). This {\bf +md5} program was originally developed as part of a suite of tools intended to +monitor large collections of files (for example, the contents of a Web site) +to detect corruption of files and inadvertent (or perhaps malicious) changes. +That task is now best accomplished with more comprehensive packages such as +\elink{Tripwire}{ftp://coast.cs.purdue.edu/pub/COAST/Tripwire/}, but the +command line {\bf md5} component continues to prove useful for verifying +correct delivery and installation of software packages, comparing the contents +of two different systems, and checking for changes in specific files. + +\subsection{Options} +\index{Options } +\addcontentsline{toc}{subsubsection}{Options} + +\begin{description} + +\item [{\bf -c}{\it signature} ] + \index{-csignature } + Computes the signature of the specified {\it infile} or the string supplied +by the {\bf -d} option and compares it against the specified {\it signature}. +If the two signatures match, the exit status will be zero, otherwise the exit +status will be 1. No signature is written to {\it outfile} or standard +output; only the exit status is set. The signature to be checked must be +specified as 32 hexadecimal digits. + +\item [{\bf -d}{\it input\_text} ] + \index{-dinput\_text } + A signature is computed for the given {\it input\_text} (which must be quoted +if it contains white space characters) instead of input from {\it infile} or +standard input. If input is specified with the {\bf -d} option, no {\it +infile} should be specified. + +\item [{\bf -u} ] + Print how-to-call information. + \end{description} + +\subsection{Files} +\index{Files } +\addcontentsline{toc}{subsubsection}{Files} + +If no {\it infile} or {\bf -d} option is specified or {\it infile} is a single +``-'', {\bf md5} reads from standard input; if no {\it outfile} is given, or +{\it outfile} is a single ``-'', output is sent to standard output. Input and +output are processed strictly serially; consequently {\bf md5} may be used in +pipelines. + +\subsection{Bugs} +\index{Bugs } +\addcontentsline{toc}{subsubsection}{Bugs} + +The mechanism used to set standard input to binary mode may be specific to +Microsoft C; if you rebuild the DOS/Windows version of the program from source +using another compiler, be sure to verify binary files work properly when read +via redirection or a pipe. + +This program has not been tested on a machine on which {\tt int} and/or {\tt +long} are longer than 32 bits. + +\section{ +\elink{Download md5.zip}{http://www.fourmilab.ch/md5/md5.zip} (Zipped +archive)} +\index{Archive!Download md5.zip Zipped } +\index{Download md5.zip (Zipped archive) } +\addcontentsline{toc}{subsection}{Download md5.zip (Zipped archive)} + +The program is provided as +\elink{md5.zip}{http://www.fourmilab.ch/md5/md5.zip}, a +\elink{Zipped}{http://www.pkware.com/} archive containing an ready-to-run +Win32 command-line executable program, {\tt md5.exe} (compiled using Microsoft +Visual C++ 5.0), and in source code form along with a {\tt Makefile} to build +the program under Unix. + +\subsection{See Also} +\index{ALSO!SEE } +\index{See Also } +\addcontentsline{toc}{subsubsection}{SEE ALSO} + +{\bf sum}(1) + +\subsection{Exit Status} +\index{Status!Exit } +\index{Exit Status } +\addcontentsline{toc}{subsubsection}{Exit Status} + +{\bf md5} returns status 0 if processing was completed without errors, 1 if +the {\bf -c} option was specified and the given signature does not match that +of the input, and 2 if processing could not be performed at all due, for +example, to a nonexistent input file. + +\subsection{Copying} +\index{Copying } +\addcontentsline{toc}{subsubsection}{Copying} + +\begin{quote} +This software is in the public domain. Permission to use, copy, modify, and +distribute this software and its documentation for any purpose and without +fee is hereby granted, without any conditions or restrictions. This software +is provided ``as is'' without express or implied warranty. +\end{quote} + +\subsection{Acknowledgements} +\index{Acknowledgements } +\addcontentsline{toc}{subsubsection}{Acknowledgements} + +The MD5 algorithm was developed by Ron Rivest. The public domain C language +implementation used in this program was written by Colin Plumb in 1993. +{\it +\elink{by John Walker}{http://www.fourmilab.ch/} +January 6th, MIM } diff --git a/docs/manuals/fr/developers/mediaformat.tex b/docs/manuals/fr/developers/mediaformat.tex new file mode 100644 index 00000000..cc824f78 --- /dev/null +++ b/docs/manuals/fr/developers/mediaformat.tex @@ -0,0 +1,1115 @@ +%% +%% + +\chapter{Storage Media Output Format} +\label{_ChapterStart9} +\index{Format!Storage Media Output} +\index{Storage Media Output Format} +\addcontentsline{toc}{section}{Storage Media Output Format} + +\section{General} +\index{General} +\addcontentsline{toc}{subsection}{General} + +This document describes the media format written by the Storage daemon. The +Storage daemon reads and writes in units of blocks. Blocks contain records. +Each block has a block header followed by records, and each record has a +record header followed by record data. + +This chapter is intended to be a technical discussion of the Media Format and +as such is not targeted at end users but rather at developers and system +administrators that want or need to know more of the working details of {\bf +Bacula}. + +\section{Definitions} +\index{Definitions} +\addcontentsline{toc}{subsection}{Definitions} + +\begin{description} + +\item [Block] + \index{Block} + A block represents the primitive unit of information that the Storage daemon +reads and writes to a physical device. Normally, for a tape device, it will +be the same as a tape block. The Storage daemon always reads and writes +blocks. A block consists of block header information followed by records. +Clients of the Storage daemon (the File daemon) normally never see blocks. +However, some of the Storage tools (bls, bscan, bextract, ...) may be use +block header information. In older Bacula tape versions, a block could +contain records (see record definition below) from multiple jobs. However, +all blocks currently written by Bacula are block level BB02, and a given +block contains records for only a single job. Different jobs simply have +their own private blocks that are intermingled with the other blocks from +other jobs on the Volume (previously the records were intermingled within +the blocks). Having only records from a single job in any give block +permitted moving the VolumeSessionId and VolumeSessionTime (see below) from +each record heading to the Block header. This has two advantages: 1. a block +can be quickly rejected based on the contents of the header without reading +all the records. 2. because there is on the average more than one record per +block, less data is written to the Volume for each job. + +\item [Record] + \index{Record} + A record consists of a Record Header, which is managed by the Storage daemon +and Record Data, which is the data received from the Client. A record is the +primitive unit of information sent to and from the Storage daemon by the +Client (File daemon) programs. The details are described below. + +\item [JobId] + \index{JobId} + A number assigned by the Director daemon for a particular job. This number +will be unique for that particular Director (Catalog). The daemons use this +number to keep track of individual jobs. Within the Storage daemon, the JobId +may not be unique if several Directors are accessing the Storage daemon +simultaneously. + +\item [Session] + \index{Session} + A Session is a concept used in the Storage daemon corresponds one to one to a +Job with the exception that each session is uniquely identified within the +Storage daemon by a unique SessionId/SessionTime pair (see below). + +\item [VolSessionId] + \index{VolSessionId} + A unique number assigned by the Storage daemon to a particular session (Job) +it is having with a File daemon. This number by itself is not unique to the +given Volume, but with the VolSessionTime, it is unique. + +\item [VolSessionTime] + \index{VolSessionTime} + A unique number assigned by the Storage daemon to a particular Storage daemon +execution. It is actually the Unix time\_t value of when the Storage daemon +began execution cast to a 32 bit unsigned integer. The combination of the +{\bf VolSessionId} and the {\bf VolSessionTime} for a given Storage daemon is +guaranteed to be unique for each Job (or session). + +\item [FileIndex] + \index{FileIndex} + A sequential number beginning at one assigned by the File daemon to the files +within a job that are sent to the Storage daemon for backup. The Storage +daemon ensures that this number is greater than zero and sequential. Note, +the Storage daemon uses negative FileIndexes to flag Session Start and End +Labels as well as End of Volume Labels. Thus, the combination of +VolSessionId, VolSessionTime, and FileIndex uniquely identifies the records +for a single file written to a Volume. + +\item [Stream] + \index{Stream} + While writing the information for any particular file to the Volume, there +can be any number of distinct pieces of information about that file, e.g. the +attributes, the file data, ... The Stream indicates what piece of data it +is, and it is an arbitrary number assigned by the File daemon to the parts +(Unix attributes, Win32 attributes, data, compressed data,\ ...) of a file +that are sent to the Storage daemon. The Storage daemon has no knowledge of +the details of a Stream; it simply represents a numbered stream of bytes. The +data for a given stream may be passed to the Storage daemon in single record, +or in multiple records. + +\item [Block Header] + \index{Block Header} + A block header consists of a block identification (``BB02''), a block length +in bytes (typically 64,512) a checksum, and sequential block number. Each +block starts with a Block Header and is followed by Records. Current block +headers also contain the VolSessionId and VolSessionTime for the records +written to that block. + +\item [Record Header] + \index{Record Header} + A record header contains the Volume Session Id, the Volume Session Time, the +FileIndex, the Stream, and the size of the data record which follows. The +Record Header is always immediately followed by a Data Record if the size +given in the Header is greater than zero. Note, for Block headers of level +BB02 (version 1.27 and later), the Record header as written to tape does not +contain the Volume Session Id and the Volume Session Time as these two +fields are stored in the BB02 Block header. The in-memory record header does +have those fields for convenience. + +\item [Data Record] + \index{Data Record} + A data record consists of a binary stream of bytes and is always preceded by +a Record Header. The details of the meaning of the binary stream of bytes are +unknown to the Storage daemon, but the Client programs (File daemon) defines +and thus knows the details of each record type. + +\item [Volume Label] + \index{Volume Label} + A label placed by the Storage daemon at the beginning of each storage volume. +It contains general information about the volume. It is written in Record +format. The Storage daemon manages Volume Labels, and if the client wants, he +may also read them. + +\item [Begin Session Label] + \index{Begin Session Label} + The Begin Session Label is a special record placed by the Storage daemon on +the storage medium as the first record of an append session job with a File +daemon. This record is useful for finding the beginning of a particular +session (Job), since no records with the same VolSessionId and VolSessionTime +will precede this record. This record is not normally visible outside of the +Storage daemon. The Begin Session Label is similar to the Volume Label except +that it contains additional information pertaining to the Session. + +\item [End Session Label] + \index{End Session Label} + The End Session Label is a special record placed by the Storage daemon on the +storage medium as the last record of an append session job with a File +daemon. The End Session Record is distinguished by a FileIndex with a value +of minus two (-2). This record is useful for detecting the end of a +particular session since no records with the same VolSessionId and +VolSessionTime will follow this record. This record is not normally visible +outside of the Storage daemon. The End Session Label is similar to the Volume +Label except that it contains additional information pertaining to the +Session. +\end{description} + +\section{Storage Daemon File Output Format} +\index{Format!Storage Daemon File Output} +\index{Storage Daemon File Output Format} +\addcontentsline{toc}{subsection}{Storage Daemon File Output Format} + +The file storage and tape storage formats are identical except that tape +records are by default blocked into blocks of 64,512 bytes, except for the +last block, which is the actual number of bytes written rounded up to a +multiple of 1024 whereas the last record of file storage is not rounded up. +The default block size of 64,512 bytes may be overridden by the user (some +older tape drives only support block sizes of 32K). Each Session written to +tape is terminated with an End of File mark (this will be removed later). +Sessions written to file are simply appended to the end of the file. + +\section{Overall Format} +\index{Format!Overall} +\index{Overall Format} +\addcontentsline{toc}{subsection}{Overall Format} + +A Bacula output file consists of Blocks of data. Each block contains a block +header followed by records. Each record consists of a record header followed +by the record data. The first record on a tape will always be the Volume Label +Record. + +No Record Header will be split across Bacula blocks. However, Record Data may +be split across any number of Bacula blocks. Obviously this will not be the +case for the Volume Label which will always be smaller than the Bacula Block +size. + +To simplify reading tapes, the Start of Session (SOS) and End of Session (EOS) +records are never split across blocks. If this is about to happen, Bacula will +write a short block before writing the session record (actually, the SOS +record should always be the first record in a block, excepting perhaps the +Volume label). + +Due to hardware limitations, the last block written to the tape may not be +fully written. If your drive permits backspace record, Bacula will backup over +the last record written on the tape, re-read it and verify that it was +correctly written. + +When a new tape is mounted Bacula will write the full contents of the +partially written block to the new tape ensuring that there is no loss of +data. When reading a tape, Bacula will discard any block that is not totally +written, thus ensuring that there is no duplication of data. In addition, +since Bacula blocks are sequentially numbered within a Job, it is easy to +ensure that no block is missing or duplicated. + +\section{Serialization} +\index{Serialization} +\addcontentsline{toc}{subsection}{Serialization} + +All Block Headers, Record Headers, and Label Records are written using +Bacula's serialization routines. These routines guarantee that the data is +written to the output volume in a machine independent format. + +\section{Block Header} +\index{Header!Block} +\index{Block Header} +\addcontentsline{toc}{subsection}{Block Header} + +The format of the Block Header (version 1.27 and later) is: + +\footnotesize +\begin{verbatim} + uint32_t CheckSum; /* Block check sum */ + uint32_t BlockSize; /* Block byte size including the header */ + uint32_t BlockNumber; /* Block number */ + char ID[4] = "BB02"; /* Identification and block level */ + uint32_t VolSessionId; /* Session Id for Job */ + uint32_t VolSessionTime; /* Session Time for Job */ +\end{verbatim} +\normalsize + +The Block header is a fixed length and fixed format and is followed by Record +Headers and Record Data. The CheckSum field is a 32 bit checksum of the block +data and the block header but not including the CheckSum field. The Block +Header is always immediately followed by a Record Header. If the tape is +damaged, a Bacula utility will be able to recover as much information as +possible from the tape by recovering blocks which are valid. The Block header +is written using the Bacula serialization routines and thus is guaranteed to +be in machine independent format. See below for version 2 of the block header. + + +\section{Record Header} +\index{Header!Record} +\index{Record Header} +\addcontentsline{toc}{subsection}{Record Header} + +Each binary data record is preceded by a Record Header. The Record Header is +fixed length and fixed format, whereas the binary data record is of variable +length. The Record Header is written using the Bacula serialization routines +and thus is guaranteed to be in machine independent format. + +The format of the Record Header (version 1.27 or later) is: + +\footnotesize +\begin{verbatim} + int32_t FileIndex; /* File index supplied by File daemon */ + int32_t Stream; /* Stream number supplied by File daemon */ + uint32_t DataSize; /* size of following data record in bytes */ +\end{verbatim} +\normalsize + +This record is followed by the binary Stream data of DataSize bytes, followed +by another Record Header record and the binary stream data. For the definitive +definition of this record, see record.h in the src/stored directory. + +Additional notes on the above: + +\begin{description} + +\item [The {\bf VolSessionId} ] + \index{VolSessionId} + is a unique sequential number that is assigned by the Storage Daemon to a +particular Job. This number is sequential since the start of execution of the +daemon. + +\item [The {\bf VolSessionTime} ] + \index{VolSessionTime} + is the time/date that the current execution of the Storage Daemon started. It +assures that the combination of VolSessionId and VolSessionTime is unique for +every jobs written to the tape, even if there was a machine crash between two +writes. + +\item [The {\bf FileIndex} ] + \index{FileIndex} + is a sequential file number within a job. The Storage daemon requires this +index to be greater than zero and sequential. Note, however, that the File +daemon may send multiple Streams for the same FileIndex. In addition, the +Storage daemon uses negative FileIndices to hold the Begin Session Label, the +End Session Label, and the End of Volume Label. + +\item [The {\bf Stream} ] + \index{Stream} + is defined by the File daemon and is used to identify separate parts of the +data saved for each file (Unix attributes, Win32 attributes, file data, +compressed file data, sparse file data, ...). The Storage Daemon has no idea +of what a Stream is or what it contains except that the Stream is required to +be a positive integer. Negative Stream numbers are used internally by the +Storage daemon to indicate that the record is a continuation of the previous +record (the previous record would not entirely fit in the block). + +For Start Session and End Session Labels (where the FileIndex is negative), +the Storage daemon uses the Stream field to contain the JobId. The current +stream definitions are: + +\footnotesize +\begin{verbatim} +#define STREAM_UNIX_ATTRIBUTES 1 /* Generic Unix attributes */ +#define STREAM_FILE_DATA 2 /* Standard uncompressed data */ +#define STREAM_MD5_SIGNATURE 3 /* MD5 signature for the file */ +#define STREAM_GZIP_DATA 4 /* GZip compressed file data */ +/* Extended Unix attributes with Win32 Extended data. Deprecated. */ +#define STREAM_UNIX_ATTRIBUTES_EX 5 /* Extended Unix attr for Win32 EX */ +#define STREAM_SPARSE_DATA 6 /* Sparse data stream */ +#define STREAM_SPARSE_GZIP_DATA 7 +#define STREAM_PROGRAM_NAMES 8 /* program names for program data */ +#define STREAM_PROGRAM_DATA 9 /* Data needing program */ +#define STREAM_SHA1_SIGNATURE 10 /* SHA1 signature for the file */ +#define STREAM_WIN32_DATA 11 /* Win32 BackupRead data */ +#define STREAM_WIN32_GZIP_DATA 12 /* Gzipped Win32 BackupRead data */ +#define STREAM_MACOS_FORK_DATA 13 /* Mac resource fork */ +#define STREAM_HFSPLUS_ATTRIBUTES 14 /* Mac OS extra attributes */ +#define STREAM_UNIX_ATTRIBUTES_ACCESS_ACL 15 /* Standard ACL attributes on UNIX */ +#define STREAM_UNIX_ATTRIBUTES_DEFAULT_ACL 16 /* Default ACL attributes on UNIX */ +\end{verbatim} +\normalsize + +\item [The {\bf DataSize} ] + \index{DataSize} + is the size in bytes of the binary data record that follows the Session +Record header. The Storage Daemon has no idea of the actual contents of the +binary data record. For standard Unix files, the data record typically +contains the file attributes or the file data. For a sparse file the first +64 bits of the file data contains the storage address for the data block. +\end{description} + +The Record Header is never split across two blocks. If there is not enough +room in a block for the full Record Header, the block is padded to the end +with zeros and the Record Header begins in the next block. The data record, on +the other hand, may be split across multiple blocks and even multiple physical +volumes. When a data record is split, the second (and possibly subsequent) +piece of the data is preceded by a new Record Header. Thus each piece of data +is always immediately preceded by a Record Header. When reading a record, if +Bacula finds only part of the data in the first record, it will automatically +read the next record and concatenate the data record to form a full data +record. + +\section{Version BB02 Block Header} +\index{Version BB02 Block Header} +\index{Header!Version BB02 Block} +\addcontentsline{toc}{subsection}{Version BB02 Block Header} + +Each session or Job has its own private block. As a consequence, the SessionId +and SessionTime are written once in each Block Header and not in the Record +Header. So, the second and current version of the Block Header BB02 is: + +\footnotesize +\begin{verbatim} + uint32_t CheckSum; /* Block check sum */ + uint32_t BlockSize; /* Block byte size including the header */ + uint32_t BlockNumber; /* Block number */ + char ID[4] = "BB02"; /* Identification and block level */ + uint32_t VolSessionId; /* Applies to all records */ + uint32_t VolSessionTime; /* contained in this block */ +\end{verbatim} +\normalsize + +As with the previous version, the BB02 Block header is a fixed length and +fixed format and is followed by Record Headers and Record Data. The CheckSum +field is a 32 bit CRC checksum of the block data and the block header but not +including the CheckSum field. The Block Header is always immediately followed +by a Record Header. If the tape is damaged, a Bacula utility will be able to +recover as much information as possible from the tape by recovering blocks +which are valid. The Block header is written using the Bacula serialization +routines and thus is guaranteed to be in machine independent format. + +\section{Version 2 Record Header} +\index{Version 2 Record Header} +\index{Header!Version 2 Record} +\addcontentsline{toc}{subsection}{Version 2 Record Header} + +Version 2 Record Header is written to the medium when using Version BB02 Block +Headers. The memory representation of the record is identical to the old BB01 +Record Header, but on the storage medium, the first two fields, namely +VolSessionId and VolSessionTime are not written. The Block Header is filled +with these values when the First user record is written (i.e. non label +record) so that when the block is written, it will have the current and unique +VolSessionId and VolSessionTime. On reading each record from the Block, the +VolSessionId and VolSessionTime is filled in the Record Header from the Block +Header. + +\section{Volume Label Format} +\index{Volume Label Format} +\index{Format!Volume Label} +\addcontentsline{toc}{subsection}{Volume Label Format} + +Tape volume labels are created by the Storage daemon in response to a {\bf +label} command given to the Console program, or alternatively by the {\bf +btape} program. created. Each volume is labeled with the following information +using the Bacula serialization routines, which guarantee machine byte order +independence. + +For Bacula versions 1.27 and later, the Volume Label Format is: + +\footnotesize +\begin{verbatim} + char Id[32]; /* Bacula 1.0 Immortal\n */ + uint32_t VerNum; /* Label version number */ + /* VerNum 11 and greater Bacula 1.27 and later */ + btime_t label_btime; /* Time/date tape labeled */ + btime_t write_btime; /* Time/date tape first written */ + /* The following are 0 in VerNum 11 and greater */ + float64_t write_date; /* Date this label written */ + float64_t write_time; /* Time this label written */ + char VolName[128]; /* Volume name */ + char PrevVolName[128]; /* Previous Volume Name */ + char PoolName[128]; /* Pool name */ + char PoolType[128]; /* Pool type */ + char MediaType[128]; /* Type of this media */ + char HostName[128]; /* Host name of writing computer */ + char LabelProg[32]; /* Label program name */ + char ProgVersion[32]; /* Program version */ + char ProgDate[32]; /* Program build date/time */ +\end{verbatim} +\normalsize + +Note, the LabelType (Volume Label, Volume PreLabel, Session Start Label, ...) +is stored in the record FileIndex field of the Record Header and does not +appear in the data part of the record. + +\section{Session Label} +\index{Label!Session} +\index{Session Label} +\addcontentsline{toc}{subsection}{Session Label} + +The Session Label is written at the beginning and end of each session as well +as the last record on the physical medium. It has the following binary format: + + +\footnotesize +\begin{verbatim} + char Id[32]; /* Bacula Immortal ... */ + uint32_t VerNum; /* Label version number */ + uint32_t JobId; /* Job id */ + uint32_t VolumeIndex; /* sequence no of vol */ + /* Prior to VerNum 11 */ + float64_t write_date; /* Date this label written */ + /* VerNum 11 and greater */ + btime_t write_btime; /* time/date record written */ + /* The following is zero VerNum 11 and greater */ + float64_t write_time; /* Time this label written */ + char PoolName[128]; /* Pool name */ + char PoolType[128]; /* Pool type */ + char JobName[128]; /* base Job name */ + char ClientName[128]; + /* Added in VerNum 10 */ + char Job[128]; /* Unique Job name */ + char FileSetName[128]; /* FileSet name */ + uint32_t JobType; + uint32_t JobLevel; +\end{verbatim} +\normalsize + +In addition, the EOS label contains: + +\footnotesize +\begin{verbatim} + /* The remainder are part of EOS label only */ + uint32_t JobFiles; + uint64_t JobBytes; + uint32_t start_block; + uint32_t end_block; + uint32_t start_file; + uint32_t end_file; + uint32_t JobErrors; +\end{verbatim} +\normalsize + +In addition, for VerNum greater than 10, the EOS label contains (in addition +to the above): + +\footnotesize +\begin{verbatim} + uint32_t JobStatus /* Job termination code */ +\end{verbatim} +\normalsize + +: Note, the LabelType (Volume Label, Volume PreLabel, Session Start Label, +...) is stored in the record FileIndex field and does not appear in the data +part of the record. Also, the Stream field of the Record Header contains the +JobId. This permits quick filtering without actually reading all the session +data in many cases. + +\section{Overall Storage Format} +\index{Format!Overall Storage} +\index{Overall Storage Format} +\addcontentsline{toc}{subsection}{Overall Storage Format} + +\footnotesize +\begin{verbatim} + Current Bacula Tape Format + 6 June 2001 + Version BB02 added 28 September 2002 + Version BB01 is the old deprecated format. + A Bacula tape is composed of tape Blocks. Each block + has a Block header followed by the block data. Block + Data consists of Records. Records consist of Record + Headers followed by Record Data. + :=======================================================: + | | + | Block Header (24 bytes) | + | | + |-------------------------------------------------------| + | | + | Record Header (12 bytes) | + | | + |-------------------------------------------------------| + | | + | Record Data | + | | + |-------------------------------------------------------| + | | + | Record Header (12 bytes) | + | | + |-------------------------------------------------------| + | | + | ... | + Block Header: the first item in each block. The format is + shown below. + Partial Data block: occurs if the data from a previous + block spills over to this block (the normal case except + for the first block on a tape). However, this partial + data block is always preceded by a record header. + Record Header: identifies the Volume Session, the Stream + and the following Record Data size. See below for format. + Record data: arbitrary binary data. + Block Header Format BB02 + :=======================================================: + | CheckSum (uint32_t) | + |-------------------------------------------------------| + | BlockSize (uint32_t) | + |-------------------------------------------------------| + | BlockNumber (uint32_t) | + |-------------------------------------------------------| + | "BB02" (char [4]) | + |-------------------------------------------------------| + | VolSessionId (uint32_t) | + |-------------------------------------------------------| + | VolSessionTime (uint32_t) | + :=======================================================: + BBO2: Serves to identify the block as a + Bacula block and also servers as a block format identifier + should we ever need to change the format. + BlockSize: is the size in bytes of the block. When reading + back a block, if the BlockSize does not agree with the + actual size read, Bacula discards the block. + CheckSum: a checksum for the Block. + BlockNumber: is the sequential block number on the tape. + VolSessionId: a unique sequential number that is assigned + by the Storage Daemon to a particular Job. + This number is sequential since the start + of execution of the daemon. + VolSessionTime: the time/date that the current execution + of the Storage Daemon started. It assures + that the combination of VolSessionId and + VolSessionTime is unique for all jobs + written to the tape, even if there was a + machine crash between two writes. + Record Header Format BB02 + :=======================================================: + | FileIndex (int32_t) | + |-------------------------------------------------------| + | Stream (int32_t) | + |-------------------------------------------------------| + | DataSize (uint32_t) | + :=======================================================: + FileIndex: a sequential file number within a job. The + Storage daemon enforces this index to be + greater than zero and sequential. Note, + however, that the File daemon may send + multiple Streams for the same FileIndex. + The Storage Daemon uses negative FileIndices + to identify Session Start and End labels + as well as the End of Volume labels. + Stream: defined by the File daemon and is intended to be + used to identify separate parts of the data + saved for each file (attributes, file data, + ...). The Storage Daemon has no idea of + what a Stream is or what it contains. + DataSize: the size in bytes of the binary data record + that follows the Session Record header. + The Storage Daemon has no idea of the + actual contents of the binary data record. + For standard Unix files, the data record + typically contains the file attributes or + the file data. For a sparse file + the first 64 bits of the data contains + the storage address for the data block. + Volume Label + :=======================================================: + | Id (32 bytes) | + |-------------------------------------------------------| + | VerNum (uint32_t) | + |-------------------------------------------------------| + | label_date (float64_t) | + | label_btime (btime_t VerNum 11 | + |-------------------------------------------------------| + | label_time (float64_t) | + | write_btime (btime_t VerNum 11 | + |-------------------------------------------------------| + | write_date (float64_t) | + | 0 (float64_t) VerNum 11 | + |-------------------------------------------------------| + | write_time (float64_t) | + | 0 (float64_t) VerNum 11 | + |-------------------------------------------------------| + | VolName (128 bytes) | + |-------------------------------------------------------| + | PrevVolName (128 bytes) | + |-------------------------------------------------------| + | PoolName (128 bytes) | + |-------------------------------------------------------| + | PoolType (128 bytes) | + |-------------------------------------------------------| + | MediaType (128 bytes) | + |-------------------------------------------------------| + | HostName (128 bytes) | + |-------------------------------------------------------| + | LabelProg (32 bytes) | + |-------------------------------------------------------| + | ProgVersion (32 bytes) | + |-------------------------------------------------------| + | ProgDate (32 bytes) | + |-------------------------------------------------------| + :=======================================================: + + Id: 32 byte Bacula identifier "Bacula 1.0 immortal\n" + (old version also recognized:) + Id: 32 byte Bacula identifier "Bacula 0.9 mortal\n" + LabelType (Saved in the FileIndex of the Header record). + PRE_LABEL -1 Volume label on unwritten tape + VOL_LABEL -2 Volume label after tape written + EOM_LABEL -3 Label at EOM (not currently implemented) + SOS_LABEL -4 Start of Session label (format given below) + EOS_LABEL -5 End of Session label (format given below) + VerNum: 11 + label_date: Julian day tape labeled + label_time: Julian time tape labeled + write_date: Julian date tape first used (data written) + write_time: Julian time tape first used (data written) + VolName: "Physical" Volume name + PrevVolName: The VolName of the previous tape (if this tape is + a continuation of the previous one). + PoolName: Pool Name + PoolType: Pool Type + MediaType: Media Type + HostName: Name of host that is first writing the tape + LabelProg: Name of the program that labeled the tape + ProgVersion: Version of the label program + ProgDate: Date Label program built + Session Label + :=======================================================: + | Id (32 bytes) | + |-------------------------------------------------------| + | VerNum (uint32_t) | + |-------------------------------------------------------| + | JobId (uint32_t) | + |-------------------------------------------------------| + | write_btime (btime_t) VerNum 11 | + |-------------------------------------------------------| + | 0 (float64_t) VerNum 11 | + |-------------------------------------------------------| + | PoolName (128 bytes) | + |-------------------------------------------------------| + | PoolType (128 bytes) | + |-------------------------------------------------------| + | JobName (128 bytes) | + |-------------------------------------------------------| + | ClientName (128 bytes) | + |-------------------------------------------------------| + | Job (128 bytes) | + |-------------------------------------------------------| + | FileSetName (128 bytes) | + |-------------------------------------------------------| + | JobType (uint32_t) | + |-------------------------------------------------------| + | JobLevel (uint32_t) | + |-------------------------------------------------------| + | FileSetMD5 (50 bytes) VerNum 11 | + |-------------------------------------------------------| + Additional fields in End Of Session Label + |-------------------------------------------------------| + | JobFiles (uint32_t) | + |-------------------------------------------------------| + | JobBytes (uint32_t) | + |-------------------------------------------------------| + | start_block (uint32_t) | + |-------------------------------------------------------| + | end_block (uint32_t) | + |-------------------------------------------------------| + | start_file (uint32_t) | + |-------------------------------------------------------| + | end_file (uint32_t) | + |-------------------------------------------------------| + | JobErrors (uint32_t) | + |-------------------------------------------------------| + | JobStatus (uint32_t) VerNum 11 | + :=======================================================: + * => fields deprecated + Id: 32 byte Bacula Identifier "Bacula 1.0 immortal\n" + LabelType (in FileIndex field of Header): + EOM_LABEL -3 Label at EOM + SOS_LABEL -4 Start of Session label + EOS_LABEL -5 End of Session label + VerNum: 11 + JobId: JobId + write_btime: Bacula time/date this tape record written + write_date: Julian date tape this record written - deprecated + write_time: Julian time tape this record written - deprecated. + PoolName: Pool Name + PoolType: Pool Type + MediaType: Media Type + ClientName: Name of File daemon or Client writing this session + Not used for EOM_LABEL. +\end{verbatim} +\normalsize + +\section{Unix File Attributes} +\index{Unix File Attributes} +\index{Attributes!Unix File} +\addcontentsline{toc}{subsection}{Unix File Attributes} + +The Unix File Attributes packet consists of the following: + +\lt{}File-Index\gt{} \lt{}Type\gt{} +\lt{}Filename\gt{}@\lt{}File-Attributes\gt{}@\lt{}Link\gt{} +@\lt{}Extended-Attributes@\gt{} where + +\begin{description} + +\item [@] + represents a byte containing a binary zero. + +\item [FileIndex] + \index{FileIndex} + is the sequential file index starting from one assigned by the File daemon. + +\item [Type] + \index{Type} + is one of the following: + +\footnotesize +\begin{verbatim} +#define FT_LNKSAVED 1 /* hard link to file already saved */ +#define FT_REGE 2 /* Regular file but empty */ +#define FT_REG 3 /* Regular file */ +#define FT_LNK 4 /* Soft Link */ +#define FT_DIR 5 /* Directory */ +#define FT_SPEC 6 /* Special file -- chr, blk, fifo, sock */ +#define FT_NOACCESS 7 /* Not able to access */ +#define FT_NOFOLLOW 8 /* Could not follow link */ +#define FT_NOSTAT 9 /* Could not stat file */ +#define FT_NOCHG 10 /* Incremental option, file not changed */ +#define FT_DIRNOCHG 11 /* Incremental option, directory not changed */ +#define FT_ISARCH 12 /* Trying to save archive file */ +#define FT_NORECURSE 13 /* No recursion into directory */ +#define FT_NOFSCHG 14 /* Different file system, prohibited */ +#define FT_NOOPEN 15 /* Could not open directory */ +#define FT_RAW 16 /* Raw block device */ +#define FT_FIFO 17 /* Raw fifo device */ +\end{verbatim} +\normalsize + +\item [Filename] + \index{Filename} + is the fully qualified filename. + +\item [File-Attributes] + \index{File-Attributes} + consists of the 13 fields of the stat() buffer in ASCII base64 format +separated by spaces. These fields and their meanings are shown below. This +stat() packet is in Unix format, and MUST be provided (constructed) for ALL +systems. + +\item [Link] + \index{Link} + when the FT code is FT\_LNK or FT\_LNKSAVED, the item in question is a Unix +link, and this field contains the fully qualified link name. When the FT code +is not FT\_LNK or FT\_LNKSAVED, this field is null. + +\item [Extended-Attributes] + \index{Extended-Attributes} + The exact format of this field is operating system dependent. It contains +additional or extended attributes of a system dependent nature. Currently, +this field is used only on WIN32 systems where it contains a ASCII base64 +representation of the WIN32\_FILE\_ATTRIBUTE\_DATA structure as defined by +Windows. The fields in the base64 representation of this structure are like +the File-Attributes separated by spaces. +\end{description} + +The File-attributes consist of the following: + +\addcontentsline{lot}{table}{File Attributes} +\begin{longtable}{|p{0.6in}|p{0.7in}|p{1in}|p{1in}|p{1.4in}|} + \hline +\multicolumn{1}{|c|}{\bf Field No. } & \multicolumn{1}{c|}{\bf Stat Name } +& \multicolumn{1}{c|}{\bf Unix } & \multicolumn{1}{c|}{\bf Win98/NT } & +\multicolumn{1}{c|}{\bf MacOS } \\ + \hline +\multicolumn{1}{|c|}{1 } & {st\_dev } & {Device number of filesystem } & +{Drive number } & {vRefNum } \\ + \hline +\multicolumn{1}{|c|}{2 } & {st\_ino } & {Inode number } & {Always 0 } & +{fileID/dirID } \\ + \hline +\multicolumn{1}{|c|}{3 } & {st\_mode } & {File mode } & {File mode } & +{777 dirs/apps; 666 docs; 444 locked docs } \\ + \hline +\multicolumn{1}{|c|}{4 } & {st\_nlink } & {Number of links to the file } & +{Number of link (only on NTFS) } & {Always 1 } \\ + \hline +\multicolumn{1}{|c|}{5 } & {st\_uid } & {Owner ID } & {Always 0 } & +{Always 0 } \\ + \hline +\multicolumn{1}{|c|}{6 } & {st\_gid } & {Group ID } & {Always 0 } & +{Always 0 } \\ + \hline +\multicolumn{1}{|c|}{7 } & {st\_rdev } & {Device ID for special files } & +{Drive No. } & {Always 0 } \\ + \hline +\multicolumn{1}{|c|}{8 } & {st\_size } & {File size in bytes } & {File +size in bytes } & {Data fork file size in bytes } \\ + \hline +\multicolumn{1}{|c|}{9 } & {st\_blksize } & {Preferred block size } & +{Always 0 } & {Preferred block size } \\ + \hline +\multicolumn{1}{|c|}{10 } & {st\_blocks } & {Number of blocks allocated } +& {Always 0 } & {Number of blocks allocated } \\ + \hline +\multicolumn{1}{|c|}{11 } & {st\_atime } & {Last access time since epoch } +& {Last access time since epoch } & {Last access time -66 years } \\ + \hline +\multicolumn{1}{|c|}{12 } & {st\_mtime } & {Last modify time since epoch } +& {Last modify time since epoch } & {Last access time -66 years } \\ + \hline +\multicolumn{1}{|c|}{13 } & {st\_ctime } & {Inode change time since epoch +} & {File create time since epoch } & {File create time -66 years} +\\ \hline + +\end{longtable} + +\section{Old Depreciated Tape Format} +\index{Old Depreciated Tape Format} +\index{Format!Old Depreciated Tape} +\addcontentsline{toc}{subsection}{Old Depreciated Tape Format} + +The format of the Block Header (version 1.26 and earlier) is: + +\footnotesize +\begin{verbatim} + uint32_t CheckSum; /* Block check sum */ + uint32_t BlockSize; /* Block byte size including the header */ + uint32_t BlockNumber; /* Block number */ + char ID[4] = "BB01"; /* Identification and block level */ +\end{verbatim} +\normalsize + +The format of the Record Header (version 1.26 or earlier) is: + +\footnotesize +\begin{verbatim} + uint32_t VolSessionId; /* Unique ID for this session */ + uint32_t VolSessionTime; /* Start time/date of session */ + int32_t FileIndex; /* File index supplied by File daemon */ + int32_t Stream; /* Stream number supplied by File daemon */ + uint32_t DataSize; /* size of following data record in bytes */ +\end{verbatim} +\normalsize + +\footnotesize +\begin{verbatim} + Current Bacula Tape Format + 6 June 2001 + Version BB01 is the old deprecated format. + A Bacula tape is composed of tape Blocks. Each block + has a Block header followed by the block data. Block + Data consists of Records. Records consist of Record + Headers followed by Record Data. + :=======================================================: + | | + | Block Header | + | (16 bytes version BB01) | + |-------------------------------------------------------| + | | + | Record Header | + | (20 bytes version BB01) | + |-------------------------------------------------------| + | | + | Record Data | + | | + |-------------------------------------------------------| + | | + | Record Header | + | (20 bytes version BB01) | + |-------------------------------------------------------| + | | + | ... | + Block Header: the first item in each block. The format is + shown below. + Partial Data block: occurs if the data from a previous + block spills over to this block (the normal case except + for the first block on a tape). However, this partial + data block is always preceded by a record header. + Record Header: identifies the Volume Session, the Stream + and the following Record Data size. See below for format. + Record data: arbitrary binary data. + Block Header Format BB01 (deprecated) + :=======================================================: + | CheckSum (uint32_t) | + |-------------------------------------------------------| + | BlockSize (uint32_t) | + |-------------------------------------------------------| + | BlockNumber (uint32_t) | + |-------------------------------------------------------| + | "BB01" (char [4]) | + :=======================================================: + BBO1: Serves to identify the block as a + Bacula block and also servers as a block format identifier + should we ever need to change the format. + BlockSize: is the size in bytes of the block. When reading + back a block, if the BlockSize does not agree with the + actual size read, Bacula discards the block. + CheckSum: a checksum for the Block. + BlockNumber: is the sequential block number on the tape. + VolSessionId: a unique sequential number that is assigned + by the Storage Daemon to a particular Job. + This number is sequential since the start + of execution of the daemon. + VolSessionTime: the time/date that the current execution + of the Storage Daemon started. It assures + that the combination of VolSessionId and + VolSessionTime is unique for all jobs + written to the tape, even if there was a + machine crash between two writes. + Record Header Format BB01 (deprecated) + :=======================================================: + | VolSessionId (uint32_t) | + |-------------------------------------------------------| + | VolSessionTime (uint32_t) | + |-------------------------------------------------------| + | FileIndex (int32_t) | + |-------------------------------------------------------| + | Stream (int32_t) | + |-------------------------------------------------------| + | DataSize (uint32_t) | + :=======================================================: + VolSessionId: a unique sequential number that is assigned + by the Storage Daemon to a particular Job. + This number is sequential since the start + of execution of the daemon. + VolSessionTime: the time/date that the current execution + of the Storage Daemon started. It assures + that the combination of VolSessionId and + VolSessionTime is unique for all jobs + written to the tape, even if there was a + machine crash between two writes. + FileIndex: a sequential file number within a job. The + Storage daemon enforces this index to be + greater than zero and sequential. Note, + however, that the File daemon may send + multiple Streams for the same FileIndex. + The Storage Daemon uses negative FileIndices + to identify Session Start and End labels + as well as the End of Volume labels. + Stream: defined by the File daemon and is intended to be + used to identify separate parts of the data + saved for each file (attributes, file data, + ...). The Storage Daemon has no idea of + what a Stream is or what it contains. + DataSize: the size in bytes of the binary data record + that follows the Session Record header. + The Storage Daemon has no idea of the + actual contents of the binary data record. + For standard Unix files, the data record + typically contains the file attributes or + the file data. For a sparse file + the first 64 bits of the data contains + the storage address for the data block. + Volume Label + :=======================================================: + | Id (32 bytes) | + |-------------------------------------------------------| + | VerNum (uint32_t) | + |-------------------------------------------------------| + | label_date (float64_t) | + |-------------------------------------------------------| + | label_time (float64_t) | + |-------------------------------------------------------| + | write_date (float64_t) | + |-------------------------------------------------------| + | write_time (float64_t) | + |-------------------------------------------------------| + | VolName (128 bytes) | + |-------------------------------------------------------| + | PrevVolName (128 bytes) | + |-------------------------------------------------------| + | PoolName (128 bytes) | + |-------------------------------------------------------| + | PoolType (128 bytes) | + |-------------------------------------------------------| + | MediaType (128 bytes) | + |-------------------------------------------------------| + | HostName (128 bytes) | + |-------------------------------------------------------| + | LabelProg (32 bytes) | + |-------------------------------------------------------| + | ProgVersion (32 bytes) | + |-------------------------------------------------------| + | ProgDate (32 bytes) | + |-------------------------------------------------------| + :=======================================================: + + Id: 32 byte Bacula identifier "Bacula 1.0 immortal\n" + (old version also recognized:) + Id: 32 byte Bacula identifier "Bacula 0.9 mortal\n" + LabelType (Saved in the FileIndex of the Header record). + PRE_LABEL -1 Volume label on unwritten tape + VOL_LABEL -2 Volume label after tape written + EOM_LABEL -3 Label at EOM (not currently implemented) + SOS_LABEL -4 Start of Session label (format given below) + EOS_LABEL -5 End of Session label (format given below) + label_date: Julian day tape labeled + label_time: Julian time tape labeled + write_date: Julian date tape first used (data written) + write_time: Julian time tape first used (data written) + VolName: "Physical" Volume name + PrevVolName: The VolName of the previous tape (if this tape is + a continuation of the previous one). + PoolName: Pool Name + PoolType: Pool Type + MediaType: Media Type + HostName: Name of host that is first writing the tape + LabelProg: Name of the program that labeled the tape + ProgVersion: Version of the label program + ProgDate: Date Label program built + Session Label + :=======================================================: + | Id (32 bytes) | + |-------------------------------------------------------| + | VerNum (uint32_t) | + |-------------------------------------------------------| + | JobId (uint32_t) | + |-------------------------------------------------------| + | *write_date (float64_t) VerNum 10 | + |-------------------------------------------------------| + | *write_time (float64_t) VerNum 10 | + |-------------------------------------------------------| + | PoolName (128 bytes) | + |-------------------------------------------------------| + | PoolType (128 bytes) | + |-------------------------------------------------------| + | JobName (128 bytes) | + |-------------------------------------------------------| + | ClientName (128 bytes) | + |-------------------------------------------------------| + | Job (128 bytes) | + |-------------------------------------------------------| + | FileSetName (128 bytes) | + |-------------------------------------------------------| + | JobType (uint32_t) | + |-------------------------------------------------------| + | JobLevel (uint32_t) | + |-------------------------------------------------------| + | FileSetMD5 (50 bytes) VerNum 11 | + |-------------------------------------------------------| + Additional fields in End Of Session Label + |-------------------------------------------------------| + | JobFiles (uint32_t) | + |-------------------------------------------------------| + | JobBytes (uint32_t) | + |-------------------------------------------------------| + | start_block (uint32_t) | + |-------------------------------------------------------| + | end_block (uint32_t) | + |-------------------------------------------------------| + | start_file (uint32_t) | + |-------------------------------------------------------| + | end_file (uint32_t) | + |-------------------------------------------------------| + | JobErrors (uint32_t) | + |-------------------------------------------------------| + | JobStatus (uint32_t) VerNum 11 | + :=======================================================: + * => fields deprecated + Id: 32 byte Bacula Identifier "Bacula 1.0 immortal\n" + LabelType (in FileIndex field of Header): + EOM_LABEL -3 Label at EOM + SOS_LABEL -4 Start of Session label + EOS_LABEL -5 End of Session label + VerNum: 11 + JobId: JobId + write_btime: Bacula time/date this tape record written + write_date: Julian date tape this record written - deprecated + write_time: Julian time tape this record written - deprecated. + PoolName: Pool Name + PoolType: Pool Type + MediaType: Media Type + ClientName: Name of File daemon or Client writing this session + Not used for EOM_LABEL. +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/developers/mempool.tex b/docs/manuals/fr/developers/mempool.tex new file mode 100644 index 00000000..a8130200 --- /dev/null +++ b/docs/manuals/fr/developers/mempool.tex @@ -0,0 +1,234 @@ +%% +%% + +\chapter{Bacula Memory Management} +\label{_ChapterStart7} +\index{Management!Bacula Memory} +\index{Bacula Memory Management} +\addcontentsline{toc}{section}{Bacula Memory Management} + +\section{General} +\index{General} +\addcontentsline{toc}{subsection}{General} + +This document describes the memory management routines that are used in Bacula +and is meant to be a technical discussion for developers rather than part of +the user manual. + +Since Bacula may be called upon to handle filenames of varying and more or +less arbitrary length, special attention needs to be used in the code to +ensure that memory buffers are sufficiently large. There are four +possibilities for memory usage within {\bf Bacula}. Each will be described in +turn. They are: + +\begin{itemize} +\item Statically allocated memory. +\item Dynamically allocated memory using malloc() and free(). +\item Non-pooled memory. +\item Pooled memory. + \end{itemize} + +\subsection{Statically Allocated Memory} +\index{Statically Allocated Memory} +\index{Memory!Statically Allocated} +\addcontentsline{toc}{subsubsection}{Statically Allocated Memory} + +Statically allocated memory is of the form: + +\footnotesize +\begin{verbatim} +char buffer[MAXSTRING]; +\end{verbatim} +\normalsize + +The use of this kind of memory is discouraged except when you are 100\% sure +that the strings to be used will be of a fixed length. One example of where +this is appropriate is for {\bf Bacula} resource names, which are currently +limited to 127 characters (MAX\_NAME\_LENGTH). Although this maximum size may +change, particularly to accommodate Unicode, it will remain a relatively small +value. + +\subsection{Dynamically Allocated Memory} +\index{Dynamically Allocated Memory} +\index{Memory!Dynamically Allocated} +\addcontentsline{toc}{subsubsection}{Dynamically Allocated Memory} + +Dynamically allocated memory is obtained using the standard malloc() routines. +As in: + +\footnotesize +\begin{verbatim} +char *buf; +buf = malloc(256); +\end{verbatim} +\normalsize + +This kind of memory can be released with: + +\footnotesize +\begin{verbatim} +free(buf); +\end{verbatim} +\normalsize + +It is recommended to use this kind of memory only when you are sure that you +know the memory size needed and the memory will be used for short periods of +time -- that is it would not be appropriate to use statically allocated +memory. An example might be to obtain a large memory buffer for reading and +writing files. When {\bf SmartAlloc} is enabled, the memory obtained by +malloc() will automatically be checked for buffer overwrite (overflow) during +the free() call, and all malloc'ed memory that is not released prior to +termination of the program will be reported as Orphaned memory. + +\subsection{Pooled and Non-pooled Memory} +\index{Memory!Pooled and Non-pooled} +\index{Pooled and Non-pooled Memory} +\addcontentsline{toc}{subsubsection}{Pooled and Non-pooled Memory} + +In order to facility the handling of arbitrary length filenames and to +efficiently handle a high volume of dynamic memory usage, we have implemented +routines between the C code and the malloc routines. The first is called +``Pooled'' memory, and is memory, which once allocated and then released, is +not returned to the system memory pool, but rather retained in a Bacula memory +pool. The next request to acquire pooled memory will return any free memory +block. In addition, each memory block has its current size associated with the +block allowing for easy checking if the buffer is of sufficient size. This +kind of memory would normally be used in high volume situations (lots of +malloc()s and free()s) where the buffer length may have to frequently change +to adapt to varying filename lengths. + +The non-pooled memory is handled by routines similar to those used for pooled +memory, allowing for easy size checking. However, non-pooled memory is +returned to the system rather than being saved in the Bacula pool. This kind +of memory would normally be used in low volume situations (few malloc()s and +free()s), but where the size of the buffer might have to be adjusted +frequently. + +\paragraph*{Types of Memory Pool:} + +Currently there are three memory pool types: + +\begin{itemize} +\item PM\_NOPOOL -- non-pooled memory. +\item PM\_FNAME -- a filename pool. +\item PM\_MESSAGE -- a message buffer pool. +\item PM\_EMSG -- error message buffer pool. + \end{itemize} + +\paragraph*{Getting Memory:} + +To get memory, one uses: + +\footnotesize +\begin{verbatim} +void *get_pool_memory(pool); +\end{verbatim} +\normalsize + +where {\bf pool} is one of the above mentioned pool names. The size of the +memory returned will be determined by the system to be most appropriate for +the application. + +If you wish non-pooled memory, you may alternatively call: + +\footnotesize +\begin{verbatim} +void *get_memory(size_t size); +\end{verbatim} +\normalsize + +The buffer length will be set to the size specified, and it will be assigned +to the PM\_NOPOOL pool (no pooling). + +\paragraph*{Releasing Memory:} + +To free memory acquired by either of the above two calls, use: + +\footnotesize +\begin{verbatim} +void free_pool_memory(void *buffer); +\end{verbatim} +\normalsize + +where buffer is the memory buffer returned when the memory was acquired. If +the memory was originally allocated as type PM\_NOPOOL, it will be released to +the system, otherwise, it will be placed on the appropriate Bacula memory pool +free chain to be used in a subsequent call for memory from that pool. + +\paragraph*{Determining the Memory Size:} + +To determine the memory buffer size, use: + +\footnotesize +\begin{verbatim} +size_t sizeof_pool_memory(void *buffer); +\end{verbatim} +\normalsize + +\paragraph*{Resizing Pool Memory:} + +To resize pool memory, use: + +\footnotesize +\begin{verbatim} +void *realloc_pool_memory(void *buffer); +\end{verbatim} +\normalsize + +The buffer will be reallocated, and the contents of the original buffer will +be preserved, but the address of the buffer may change. + +\paragraph*{Automatic Size Adjustment:} + +To have the system check and if necessary adjust the size of your pooled +memory buffer, use: + +\footnotesize +\begin{verbatim} +void *check_pool_memory_size(void *buffer, size_t new-size); +\end{verbatim} +\normalsize + +where {\bf new-size} is the buffer length needed. Note, if the buffer is +already equal to or larger than {\bf new-size} no buffer size change will +occur. However, if a buffer size change is needed, the original contents of +the buffer will be preserved, but the buffer address may change. Many of the +low level Bacula subroutines expect to be passed a pool memory buffer and use +this call to ensure the buffer they use is sufficiently large. + +\paragraph*{Releasing All Pooled Memory:} + +In order to avoid orphaned buffer error messages when terminating the program, +use: + +\footnotesize +\begin{verbatim} +void close_memory_pool(); +\end{verbatim} +\normalsize + +to free all unused memory retained in the Bacula memory pool. Note, any memory +not returned to the pool via free\_pool\_memory() will not be released by this +call. + +\paragraph*{Pooled Memory Statistics:} + +For debugging purposes and performance tuning, the following call will print +the current memory pool statistics: + +\footnotesize +\begin{verbatim} +void print_memory_pool_stats(); +\end{verbatim} +\normalsize + +an example output is: + +\footnotesize +\begin{verbatim} +Pool Maxsize Maxused Inuse + 0 256 0 0 + 1 256 1 0 + 2 256 1 0 +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/developers/netprotocol.tex b/docs/manuals/fr/developers/netprotocol.tex new file mode 100644 index 00000000..45c2a8ed --- /dev/null +++ b/docs/manuals/fr/developers/netprotocol.tex @@ -0,0 +1,224 @@ +%% +%% + +\chapter{TCP/IP Network Protocol} +\label{_ChapterStart5} +\index{TCP/IP Network Protocol} +\index{Protocol!TCP/IP Network} +\addcontentsline{toc}{section}{TCP/IP Network Protocol} + +\section{General} +\index{General} +\addcontentsline{toc}{subsection}{General} + +This document describes the TCP/IP protocol used by Bacula to communicate +between the various daemons and services. The definitive definition of the +protocol can be found in src/lib/bsock.h, src/lib/bnet.c and +src/lib/bnet\_server.c. + +Bacula's network protocol is basically a ``packet oriented'' protocol built on +a standard TCP/IP streams. At the lowest level all packet transfers are done +with read() and write() requests on system sockets. Pipes are not used as they +are considered unreliable for large serial data transfers between various +hosts. + +Using the routines described below (bnet\_open, bnet\_write, bnet\_recv, and +bnet\_close) guarantees that the number of bytes you write into the socket +will be received as a single record on the other end regardless of how many +low level write() and read() calls are needed. All data transferred are +considered to be binary data. + +\section{bnet and Threads} +\index{Threads!bnet and} +\index{Bnet and Threads} +\addcontentsline{toc}{subsection}{bnet and Threads} + +These bnet routines work fine in a threaded environment. However, they assume +that there is only one reader or writer on the socket at any time. It is +highly recommended that only a single thread access any BSOCK packet. The +exception to this rule is when the socket is first opened and it is waiting +for a job to start. The wait in the Storage daemon is done in one thread and +then passed to another thread for subsequent handling. + +If you envision having two threads using the same BSOCK, think twice, then you +must implement some locking mechanism. However, it probably would not be +appropriate to put locks inside the bnet subroutines for efficiency reasons. + +\section{bnet\_open} +\index{Bnet\_open} +\addcontentsline{toc}{subsection}{bnet\_open} + +To establish a connection to a server, use the subroutine: + +BSOCK *bnet\_open(void *jcr, char *host, char *service, int port, int *fatal) +bnet\_open(), if successful, returns the Bacula sock descriptor pointer to be +used in subsequent bnet\_send() and bnet\_read() requests. If not successful, +bnet\_open() returns a NULL. If fatal is set on return, it means that a fatal +error occurred and that you should not repeatedly call bnet\_open(). Any error +message will generally be sent to the JCR. + +\section{bnet\_send} +\index{Bnet\_send} +\addcontentsline{toc}{subsection}{bnet\_send} + +To send a packet, one uses the subroutine: + +int bnet\_send(BSOCK *sock) This routine is equivalent to a write() except +that it handles the low level details. The data to be sent is expected to be +in sock-\gt{}msg and be sock-\gt{}msglen bytes. To send a packet, bnet\_send() +first writes four bytes in network byte order than indicate the size of the +following data packet. It returns: + +\footnotesize +\begin{verbatim} + Returns 0 on failure + Returns 1 on success +\end{verbatim} +\normalsize + +In the case of a failure, an error message will be sent to the JCR contained +within the bsock packet. + +\section{bnet\_fsend} +\index{Bnet\_fsend} +\addcontentsline{toc}{subsection}{bnet\_fsend} + +This form uses: + +int bnet\_fsend(BSOCK *sock, char *format, ...) and it allows you to send a +formatted messages somewhat like fprintf(). The return status is the same as +bnet\_send. + +\section{Additional Error information} +\index{Information!Additional Error} +\index{Additional Error information} +\addcontentsline{toc}{subsection}{Additional Error information} + +Fro additional error information, you can call {\bf is\_bnet\_error(BSOCK +*bsock)} which will return 0 if there is no error or non-zero if there is an +error on the last transmission. The {\bf is\_bnet\_stop(BSOCK *bsock)} +function will return 0 if there no errors and you can continue sending. It +will return non-zero if there are errors or the line is closed (no more +transmissions should be sent). + +\section{bnet\_recv} +\index{Bnet\_recv} +\addcontentsline{toc}{subsection}{bnet\_recv} + +To read a packet, one uses the subroutine: + +int bnet\_recv(BSOCK *sock) This routine is similar to a read() except that it +handles the low level details. bnet\_read() first reads packet length that +follows as four bytes in network byte order. The data is read into +sock-\gt{}msg and is sock-\gt{}msglen bytes. If the sock-\gt{}msg is not large +enough, bnet\_recv() realloc() the buffer. It will return an error (-2) if +maxbytes is less than the record size sent. It returns: + +\footnotesize +\begin{verbatim} + * Returns number of bytes read + * Returns 0 on end of file + * Returns -1 on hard end of file (i.e. network connection close) + * Returns -2 on error +\end{verbatim} +\normalsize + +It should be noted that bnet\_recv() is a blocking read. + +\section{bnet\_sig} +\index{Bnet\_sig} +\addcontentsline{toc}{subsection}{bnet\_sig} + +To send a ``signal'' from one daemon to another, one uses the subroutine: + +int bnet\_sig(BSOCK *sock, SIGNAL) where SIGNAL is one of the following: + +\begin{enumerate} +\item BNET\_EOF - deprecated use BNET\_EOD +\item BNET\_EOD - End of data stream, new data may follow +\item BNET\_EOD\_POLL - End of data and poll all in one +\item BNET\_STATUS - Request full status +\item BNET\_TERMINATE - Conversation terminated, doing close() +\item BNET\_POLL - Poll request, I'm hanging on a read +\item BNET\_HEARTBEAT - Heartbeat Response requested +\item BNET\_HB\_RESPONSE - Only response permitted to HB +\item BNET\_PROMPT - Prompt for UA + \end{enumerate} + +\section{bnet\_strerror} +\index{Bnet\_strerror} +\addcontentsline{toc}{subsection}{bnet\_strerror} + +Returns a formated string corresponding to the last error that occurred. + +\section{bnet\_close} +\index{Bnet\_close} +\addcontentsline{toc}{subsection}{bnet\_close} + +The connection with the server remains open until closed by the subroutine: + +void bnet\_close(BSOCK *sock) + +\section{Becoming a Server} +\index{Server!Becoming a} +\index{Becoming a Server} +\addcontentsline{toc}{subsection}{Becoming a Server} + +The bnet\_open() and bnet\_close() routines described above are used on the +client side to establish a connection and terminate a connection with the +server. To become a server (i.e. wait for a connection from a client), use the +routine {\bf bnet\_thread\_server}. The calling sequence is a bit complicated, +please refer to the code in bnet\_server.c and the code at the beginning of +each daemon as examples of how to call it. + +\section{Higher Level Conventions} +\index{Conventions!Higher Level} +\index{Higher Level Conventions} +\addcontentsline{toc}{subsection}{Higher Level Conventions} + +Within Bacula, we have established the convention that any time a single +record is passed, it is sent with bnet\_send() and read with bnet\_recv(). +Thus the normal exchange between the server (S) and the client (C) are: + +\footnotesize +\begin{verbatim} +S: wait for connection C: attempt connection +S: accept connection C: bnet_send() send request +S: bnet_recv() wait for request +S: act on request +S: bnet_send() send ack C: bnet_recv() wait for ack +\end{verbatim} +\normalsize + +Thus a single command is sent, acted upon by the server, and then +acknowledged. + +In certain cases, such as the transfer of the data for a file, all the +information or data cannot be sent in a single packet. In this case, the +convention is that the client will send a command to the server, who knows +that more than one packet will be returned. In this case, the server will +enter a loop: + +\footnotesize +\begin{verbatim} +while ((n=bnet_recv(bsock)) > 0) { + act on request +} +if (n < 0) + error +\end{verbatim} +\normalsize + +The client will perform the following: + +\footnotesize +\begin{verbatim} +bnet_send(bsock); +bnet_send(bsock); +... +bnet_sig(bsock, BNET_EOD); +\end{verbatim} +\normalsize + +Thus the client will send multiple packets and signal to the server when all +the packets have been sent by sending a zero length record. diff --git a/docs/manuals/fr/developers/platformsupport.tex b/docs/manuals/fr/developers/platformsupport.tex new file mode 100644 index 00000000..a04e56f7 --- /dev/null +++ b/docs/manuals/fr/developers/platformsupport.tex @@ -0,0 +1,107 @@ +%% +%% + +\chapter{Platform Support} +\label{_PlatformChapter} +\index{Support!Platform} +\index{Platform Support} +\addcontentsline{toc}{section}{Platform Support} + +\section{General} +\index{General } +\addcontentsline{toc}{subsection}{General} + +This chapter describes the requirements for having a +supported platform (Operating System). In general, Bacula is +quite portable. It supports 32 and 64 bit architectures as well +as bigendian and littleendian machines. For full +support, the platform (Operating System) must implement POSIX Unix +system calls. However, for File daemon support only, a small +compatibility library can be written to support almost any +architecture. + +Currently Linux, FreeBSD, and Solaris are fully supported +platforms, which means that the code has been tested on those +machines and passes a full set of regression tests. + +In addition, the Windows File daemon is supported on most versions +of Windows, and finally, there are a number of other platforms +where the File daemon (client) is known to run: NetBSD, OpenBSD, +Mac OSX, SGI, ... + +\section{Requirements to become a Supported Platform} +\index{Requirements!Platform} +\index{Platform Requirements} +\addcontentsline{toc}{subsection}{Platform Requirements} + +As mentioned above, in order to become a fully supported platform, it +must support POSIX Unix system calls. In addition, the following +requirements must be met: + +\begin{itemize} +\item The principal developer (currently Kern) must have + non-root ssh access to a test machine running the platform. +\item The ideal requirements and minimum requirements + for this machine are given below. +\item There must be a defined platform champion who is normally + a system administrator for the machine that is available. This + person need not be a developer/programmer but must be familiar + with system administration of the platform. +\item There must be at least one person designated who will + run regression tests prior to each release. Releases occur + approximately once every 6 months, but can be more frequent. + It takes at most a day's effort to setup the regression scripts + in the beginning, and after that, they can either be run daily + or on demand before a release. Running the regression scripts + involves only one or two command line commands and is fully + automated. +\item Ideally there are one or more persons who will package + each Bacula release. +\item Ideally there are one or more developers who can respond to + and fix platform specific bugs. +\end{itemize} + +Ideal requirements for a test machine: +\begin{itemize} +\item The principal developer will have non-root ssh access to + the test machine at all times. +\item The pricipal developer will have a root password. +\item The test machine will provide approximately 200 MB of + disk space for continual use. +\item The test machine will have approximately 500 MB of free + disk space for temporary use. +\item The test machine will run the most common version of the OS. +\item The test machine will have an autochanger of DDS-4 technology + or later having two or more tapes. +\item The test machine will have MySQL and/or PostgreSQL database + access for account "bacula" available. +\item The test machine will have sftp access. +\item The test machine will provide an smtp server. +\end{itemize} + +Minimum requirements for a test machine: +\begin{itemize} +\item The principal developer will have non-root ssh access to + the test machine when requested approximately once a month. +\item The pricipal developer not have root access. +\item The test machine will provide approximately 80 MB of + disk space for continual use. +\item The test machine will have approximately 300 MB of free + disk space for temporary use. +\item The test machine will run the the OS. +\item The test machine will have a tape drive of DDS-4 technology + or later that can be scheduled for access. +\item The test machine will not have MySQL and/or PostgreSQL database + access. +\item The test machine will have no sftp access. +\item The test machine will provide no email access. +\end{itemize} + +Bare bones test machine requirements: +\begin{itemize} +\item The test machine is available only to a designated + test person (your own machine). +\item The designated test person runs the regession + tests on demand. +\item The test machine has a tape drive available. +\end{itemize} diff --git a/docs/manuals/fr/developers/porting.tex b/docs/manuals/fr/developers/porting.tex new file mode 100644 index 00000000..278f0e5d --- /dev/null +++ b/docs/manuals/fr/developers/porting.tex @@ -0,0 +1,173 @@ +%% +%% + +\chapter{Bacula Porting Notes} +\label{_ChapterStart1} +\index{Notes!Bacula Porting} +\index{Bacula Porting Notes} +\addcontentsline{toc}{section}{Bacula Porting Notes} + +This document is intended mostly for developers who wish to port Bacula to a +system that is not {\bf officially} supported. + +It is hoped that Bacula clients will eventually run on every imaginable system +that needs backing up (perhaps even a Palm). It is also hoped that the Bacula +Directory and Storage daemons will run on every system capable of supporting +them. + +\section{Porting Requirements} +\index{Requirements!Porting} +\index{Porting Requirements} +\addcontentsline{toc}{section}{Porting Requirements} + +In General, the following holds true: + +\begin{itemize} +\item {\bf Bacula} has been compiled and run on Linux RedHat, FreeBSD, and + Solaris systems. +\item In addition, clients exist on Win32, and Irix +\item It requires GNU C++ to compile. You can try with other compilers, but + you are on your own. The Irix client is built with the Irix complier, but, in + general, you will need GNU. +\item Your compiler must provide support for 64 bit signed and unsigned + integers. +\item You will need a recent copy of the {\bf autoconf} tools loaded on your + system (version 2.13 or later). The {\bf autoconf} tools are used to build + the configuration program, but are not part of the Bacula source +distribution. +\item There are certain third party packages that Bacula needs. Except for + MySQL, they can all be found in the {\bf depkgs} and {\bf depkgs1} releases. +\item To build the Win32 binaries, we use Microsoft VC++ standard + 2003. Please see the instructions in + bacula-source/src/win32/README.win32 for more details. If you + want to use VC++ Express, please see README.vc8. Our build is + done under the most recent version of Cygwin, but Cygwin is + not used in the Bacula binaries that are produced. + Unfortunately, we do not have the resources to help you build + your own version of the Win32 FD, so you are pretty much on + your own. You can ask the bacula-devel list for help, but + please don't expect much. +\item {\bf Bacula} requires a good implementation of pthreads to work. +\item The source code has been written with portability in mind and is mostly + POSIX compatible. Thus porting to any POSIX compatible operating system + should be relatively easy. +\end{itemize} + +\section{Steps to Take for Porting} +\index{Porting!Steps to Take for} +\index{Steps to Take for Porting} +\addcontentsline{toc}{section}{Steps to Take for Porting} + +\begin{itemize} +\item The first step is to ensure that you have version 2.13 or later of the + {\bf autoconf} tools loaded. You can skip this step, but making changes to + the configuration program will be difficult or impossible. +\item The run a {\bf ./configure} command in the main source directory and + examine the output. It should look something like the following: + +\footnotesize +\begin{verbatim} +Configuration on Mon Oct 28 11:42:27 CET 2002: + Host: i686-pc-linux-gnu -- redhat 7.3 + Bacula version: 1.27 (26 October 2002) + Source code location: . + Install binaries: /sbin + Install config files: /etc/bacula + C Compiler: gcc + C++ Compiler: c++ + Compiler flags: -g -O2 + Linker flags: + Libraries: -lpthread + Statically Linked Tools: no + Database found: no + Database type: Internal + Database lib: + Job Output Email: root@localhost + Traceback Email: root@localhost + SMTP Host Address: localhost + Director Port 9101 + File daemon Port 9102 + Storage daemon Port 9103 + Working directory /etc/bacula/working + SQL binaries Directory + Large file support: yes + readline support: yes + cweb support: yes /home/kern/bacula/depkgs/cweb + TCP Wrappers support: no + ZLIB support: yes + enable-smartalloc: yes + enable-gnome: no + gmp support: yes +\end{verbatim} +\normalsize + +The details depend on your system. The first thing to check is that it +properly identified your host on the {\bf Host:} line. The first part (added +in version 1.27) is the GNU four part identification of your system. The part +after the -- is your system and the system version. Generally, if your system +is not yet supported, you must correct these. +\item If the {\bf ./configure} does not function properly, you must determine + the cause and fix it. Generally, it will be because some required system + routine is not available on your machine. +\item To correct problems with detection of your system type or with routines + and libraries, you must edit the file {\bf + \lt{}bacula-src\gt{}/autoconf/configure.in}. This is the ``source'' from +which {\bf configure} is built. In general, most of the changes for your +system will be made in {\bf autoconf/aclocal.m4} in the routine {\bf +BA\_CHECK\_OPSYS} or in the routine {\bf BA\_CHECK\_OPSYS\_DISTNAME}. I have +already added the necessary code for most systems, but if yours shows up as +{\bf unknown} you will need to make changes. Then as mentioned above, you +will need to set a number of system dependent items in {\bf configure.in} in +the {\bf case} statement at approximately line 1050 (depending on the Bacula +release). +\item The items to in the case statement that corresponds to your system are + the following: + +\begin{itemize} +\item DISTVER -- set to the version of your operating system. Typically some + form of {\bf uname} obtains it. +\item TAPEDRIVE -- the default tape drive. Not too important as the user can + set it as an option. +\item PSCMD -- set to the {\bf ps} command that will provide the PID in the + first field and the program name in the second field. If this is not set + properly, the {\bf bacula stop} script will most likely not be able to stop +Bacula in all cases. +\item hostname -- command to return the base host name (non-qualified) of + your system. This is generally the machine name. Not too important as the + user can correct this in his configuration file. +\item CFLAGS -- set any special compiler flags needed. Many systems need a + special flag to make pthreads work. See cygwin for an example. +\item LDFLAGS -- set any special loader flags. See cygwin for an example. +\item PTHREAD\_LIB -- set for any special pthreads flags needed during + linking. See freebsd as an example. +\item lld -- set so that a ``long long int'' will be properly edited in a + printf() call. +\item llu -- set so that a ``long long unsigned'' will be properly edited in + a printf() call. +\item PFILES -- set to add any files that you may define is your platform + subdirectory. These files are used for installation of automatic system + startup of Bacula daemons. +\end{itemize} + +\item To rebuild a new version of {\bf configure} from a changed {\bf + autoconf/configure.in} you enter {\bf make configure} in the top level Bacula + source directory. You must have done a ./configure prior to trying to rebuild + the configure script or it will get into an infinite loop. +\item If the {\bf make configure} gets into an infinite loop, ctl-c it, then + do {\bf ./configure} (no options are necessary) and retry the {\bf make + configure}, which should now work. +\item To rebuild {\bf configure} you will need to have {\bf autoconf} version + 2.57-3 or higher loaded. Older versions of autoconf will complain about + unknown or bad options, and won't work. +\item After you have a working {\bf configure} script, you may need to make a + few system dependent changes to the way Bacula works. Generally, these are + done in {\bf src/baconfig.h}. You can find a few examples of system dependent +changes toward the end of this file. For example, on Irix systems, there is +no definition for {\bf socklen\_t}, so it is made in this file. If your +system has structure alignment requirements, check the definition of BALIGN +in this file. Currently, all Bacula allocated memory is aligned on a {\bf +double} boundary. +\item If you are having problems with Bacula's type definitions, you might + look at {\bf src/bc\_types.h} where all the types such as {\bf uint32\_t}, + {\bf uint64\_t}, etc. that Bacula uses are defined. +\end{itemize} diff --git a/docs/manuals/fr/developers/setup.sm b/docs/manuals/fr/developers/setup.sm new file mode 100644 index 00000000..7c88dc61 --- /dev/null +++ b/docs/manuals/fr/developers/setup.sm @@ -0,0 +1,23 @@ +/* + * html2latex + */ + +available { + sun4_sunos.4 + sun4_solaris.2 + rs_aix.3 + rs_aix.4 + sgi_irix +} + +description { + From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX +} + +install { + bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex + bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag + bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag + bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag + man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1 +} diff --git a/docs/manuals/fr/developers/smartall.tex b/docs/manuals/fr/developers/smartall.tex new file mode 100644 index 00000000..41f66f08 --- /dev/null +++ b/docs/manuals/fr/developers/smartall.tex @@ -0,0 +1,432 @@ +%% +%% + +\addcontentsline{lof}{figure}{Smart Memory Allocation with Orphaned Buffer +Detection} +\includegraphics{./smartall.eps} + +\chapter{Smart Memory Allocation} +\label{_ChapterStart4} +\index{Detection!Smart Memory Allocation With Orphaned Buffer } +\index{Smart Memory Allocation With Orphaned Buffer Detection } +\addcontentsline{toc}{section}{Smart Memory Allocation With Orphaned Buffer +Detection} + +Few things are as embarrassing as a program that leaks, yet few errors are so +easy to commit or as difficult to track down in a large, complicated program +as failure to release allocated memory. SMARTALLOC replaces the standard C +library memory allocation functions with versions which keep track of buffer +allocations and releases and report all orphaned buffers at the end of program +execution. By including this package in your program during development and +testing, you can identify code that loses buffers right when it's added and +most easily fixed, rather than as part of a crisis debugging push when the +problem is identified much later in the testing cycle (or even worse, when the +code is in the hands of a customer). When program testing is complete, simply +recompiling with different flags removes SMARTALLOC from your program, +permitting it to run without speed or storage penalties. + +In addition to detecting orphaned buffers, SMARTALLOC also helps to find other +common problems in management of dynamic storage including storing before the +start or beyond the end of an allocated buffer, referencing data through a +pointer to a previously released buffer, attempting to release a buffer twice +or releasing storage not obtained from the allocator, and assuming the initial +contents of storage allocated by functions that do not guarantee a known +value. SMARTALLOC's checking does not usually add a large amount of overhead +to a program (except for programs which use {\tt realloc()} extensively; see +below). SMARTALLOC focuses on proper storage management rather than internal +consistency of the heap as checked by the malloc\_debug facility available on +some systems. SMARTALLOC does not conflict with malloc\_debug and both may be +used together, if you wish. SMARTALLOC makes no assumptions regarding the +internal structure of the heap and thus should be compatible with any C +language implementation of the standard memory allocation functions. + +\subsection{ Installing SMARTALLOC} +\index{SMARTALLOC!Installing } +\index{Installing SMARTALLOC } +\addcontentsline{toc}{subsection}{Installing SMARTALLOC} + +SMARTALLOC is provided as a Zipped archive, +\elink{smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}; see the +download instructions below. + +To install SMARTALLOC in your program, simply add the statement: + +to every C program file which calls any of the memory allocation functions +({\tt malloc}, {\tt calloc}, {\tt free}, etc.). SMARTALLOC must be used for +all memory allocation with a program, so include file for your entire program, +if you have such a thing. Next, define the symbol SMARTALLOC in the +compilation before the inclusion of smartall.h. I usually do this by having my +Makefile add the ``{\tt -DSMARTALLOC}'' option to the C compiler for +non-production builds. You can define the symbol manually, if you prefer, by +adding the statement: + +{\tt \#define SMARTALLOC} + +At the point where your program is all done and ready to relinquish control to +the operating system, add the call: + +{\tt \ \ \ \ \ \ \ \ sm\_dump(}{\it datadump}{\tt );} + +where {\it datadump} specifies whether the contents of orphaned buffers are to +be dumped in addition printing to their size and place of allocation. The data +are dumped only if {\it datadump} is nonzero, so most programs will normally +use ``{\tt sm\_dump(0);}''. If a mysterious orphaned buffer appears that can't +be identified from the information this prints about it, replace the statement +with ``{\tt sm\_dump(1)};''. Usually the dump of the buffer's data will +furnish the additional clues you need to excavate and extirpate the elusive +error that left the buffer allocated. + +Finally, add the files ``smartall.h'' and ``smartall.c'' from this release to +your source directory, make dependencies, and linker input. You needn't make +inclusion of smartall.c in your link optional; if compiled with SMARTALLOC not +defined it generates no code, so you may always include it knowing it will +waste no storage in production builds. Now when you run your program, if it +leaves any buffers around when it's done, each will be reported by {\tt +sm\_dump()} on stderr as follows: + +\footnotesize +\begin{verbatim} +Orphaned buffer: 120 bytes allocated at line 50 of gutshot.c +\end{verbatim} +\normalsize + +\subsection{ Squelching a SMARTALLOC} +\index{SMARTALLOC!Squelching a } +\index{Squelching a SMARTALLOC } +\addcontentsline{toc}{subsection}{Squelching a SMARTALLOC} + +Usually, when you first install SMARTALLOC in an existing program you'll find +it nattering about lots of orphaned buffers. Some of these turn out to be +legitimate errors, but some are storage allocated during program +initialisation that, while dynamically allocated, is logically static storage +not intended to be released. Of course, you can get rid of the complaints +about these buffers by adding code to release them, but by doing so you're +adding unnecessary complexity and code size to your program just to silence +the nattering of a SMARTALLOC, so an escape hatch is provided to eliminate the +need to release these buffers. + +Normally all storage allocated with the functions {\tt malloc()}, {\tt +calloc()}, and {\tt realloc()} is monitored by SMARTALLOC. If you make the +function call: + +\footnotesize +\begin{verbatim} + sm_static(1); +\end{verbatim} +\normalsize + +you declare that subsequent storage allocated by {\tt malloc()}, {\tt +calloc()}, and {\tt realloc()} should not be considered orphaned if found to +be allocated when {\tt sm\_dump()} is called. I use a call on ``{\tt +sm\_static(1);}'' before I allocate things like program configuration tables +so I don't have to add code to release them at end of program time. After +allocating unmonitored data this way, be sure to add a call to: + +\footnotesize +\begin{verbatim} + sm_static(0); +\end{verbatim} +\normalsize + +to resume normal monitoring of buffer allocations. Buffers allocated while +{\tt sm\_static(1}) is in effect are not checked for having been orphaned but +all the other safeguards provided by SMARTALLOC remain in effect. You may +release such buffers, if you like; but you don't have to. + +\subsection{ Living with Libraries} +\index{Libraries!Living with } +\index{Living with Libraries } +\addcontentsline{toc}{subsection}{Living with Libraries} + +Some library functions for which source code is unavailable may gratuitously +allocate and return buffers that contain their results, or require you to pass +them buffers which they subsequently release. If you have source code for the +library, by far the best approach is to simply install SMARTALLOC in it, +particularly since this kind of ill-structured dynamic storage management is +the source of so many storage leaks. Without source code, however, there's no +option but to provide a way to bypass SMARTALLOC for the buffers the library +allocates and/or releases with the standard system functions. + +For each function {\it xxx} redefined by SMARTALLOC, a corresponding routine +named ``{\tt actually}{\it xxx}'' is furnished which provides direct access to +the underlying system function, as follows: + +\begin{quote} + +\begin{longtable}{ll} +\multicolumn{1}{l }{\bf Standard function } & \multicolumn{1}{l }{\bf Direct +access function } \\ +{{\tt malloc(}{\it size}{\tt )} } & {{\tt actuallymalloc(}{\it size}{\tt )} +} \\ +{{\tt calloc(}{\it nelem}{\tt ,} {\it elsize}{\tt )} } & {{\tt +actuallycalloc(}{\it nelem}, {\it elsize}{\tt )} } \\ +{{\tt realloc(}{\it ptr}{\tt ,} {\it size}{\tt )} } & {{\tt +actuallyrealloc(}{\it ptr}, {\it size}{\tt )} } \\ +{{\tt free(}{\it ptr}{\tt )} } & {{\tt actuallyfree(}{\it ptr}{\tt )} } + +\end{longtable} + +\end{quote} + +For example, suppose there exists a system library function named ``{\tt +getimage()}'' which reads a raster image file and returns the address of a +buffer containing it. Since the library routine allocates the image directly +with {\tt malloc()}, you can't use SMARTALLOC's {\tt free()}, as that call +expects information placed in the buffer by SMARTALLOC's special version of +{\tt malloc()}, and hence would report an error. To release the buffer you +should call {\tt actuallyfree()}, as in this code fragment: + +\footnotesize +\begin{verbatim} + struct image *ibuf = getimage("ratpack.img"); + display_on_screen(ibuf); + actuallyfree(ibuf); +\end{verbatim} +\normalsize + +Conversely, suppose we are to call a library function, ``{\tt putimage()}'', +which writes an image buffer into a file and then releases the buffer with +{\tt free()}. Since the system {\tt free()} is being called, we can't pass a +buffer allocated by SMARTALLOC's allocation routines, as it contains special +information that the system {\tt free()} doesn't expect to be there. The +following code uses {\tt actuallymalloc()} to obtain the buffer passed to such +a routine. + +\footnotesize +\begin{verbatim} + struct image *obuf = + (struct image *) actuallymalloc(sizeof(struct image)); + dump_screen_to_image(obuf); + putimage("scrdump.img", obuf); /* putimage() releases obuf */ +\end{verbatim} +\normalsize + +It's unlikely you'll need any of the ``actually'' calls except under very odd +circumstances (in four products and three years, I've only needed them once), +but they're there for the rare occasions that demand them. Don't use them to +subvert the error checking of SMARTALLOC; if you want to disable orphaned +buffer detection, use the {\tt sm\_static(1)} mechanism described above. That +way you don't forfeit all the other advantages of SMARTALLOC as you do when +using {\tt actuallymalloc()} and {\tt actuallyfree()}. + +\subsection{ SMARTALLOC Details} +\index{SMARTALLOC Details } +\index{Details!SMARTALLOC } +\addcontentsline{toc}{subsection}{SMARTALLOC Details} + +When you include ``smartall.h'' and define SMARTALLOC, the following standard +system library functions are redefined with the \#define mechanism to call +corresponding functions within smartall.c instead. (For details of the +redefinitions, please refer to smartall.h.) + +\footnotesize +\begin{verbatim} + void *malloc(size_t size) + void *calloc(size_t nelem, size_t elsize) + void *realloc(void *ptr, size_t size) + void free(void *ptr) + void cfree(void *ptr) +\end{verbatim} +\normalsize + +{\tt cfree()} is a historical artifact identical to {\tt free()}. + +In addition to allocating storage in the same way as the standard library +functions, the SMARTALLOC versions expand the buffers they allocate to include +information that identifies where each buffer was allocated and to chain all +allocated buffers together. When a buffer is released, it is removed from the +allocated buffer chain. A call on {\tt sm\_dump()} is able, by scanning the +chain of allocated buffers, to find all orphaned buffers. Buffers allocated +while {\tt sm\_static(1)} is in effect are specially flagged so that, despite +appearing on the allocated buffer chain, {\tt sm\_dump()} will not deem them +orphans. + +When a buffer is allocated by {\tt malloc()} or expanded with {\tt realloc()}, +all bytes of newly allocated storage are set to the hexadecimal value 0x55 +(alternating one and zero bits). Note that for {\tt realloc()} this applies +only to the bytes added at the end of buffer; the original contents of the +buffer are not modified. Initializing allocated storage to a distinctive +nonzero pattern is intended to catch code that erroneously assumes newly +allocated buffers are cleared to zero; in fact their contents are random. The +{\tt calloc()} function, defined as returning a buffer cleared to zero, +continues to zero its buffers under SMARTALLOC. + +Buffers obtained with the SMARTALLOC functions contain a special sentinel byte +at the end of the user data area. This byte is set to a special key value +based upon the buffer's memory address. When the buffer is released, the key +is tested and if it has been overwritten an assertion in the {\tt free} +function will fail. This catches incorrect program code that stores beyond the +storage allocated for the buffer. At {\tt free()} time the queue links are +also validated and an assertion failure will occur if the program has +destroyed them by storing before the start of the allocated storage. + +In addition, when a buffer is released with {\tt free()}, its contents are +immediately destroyed by overwriting them with the hexadecimal pattern 0xAA +(alternating bits, the one's complement of the initial value pattern). This +will usually trip up code that keeps a pointer to a buffer that's been freed +and later attempts to reference data within the released buffer. Incredibly, +this is {\it legal} in the standard Unix memory allocation package, which +permits programs to free() buffers, then raise them from the grave with {\tt +realloc()}. Such program ``logic'' should be fixed, not accommodated, and +SMARTALLOC brooks no such Lazarus buffer`` nonsense. + +Some C libraries allow a zero size argument in calls to {\tt malloc()}. Since +this is far more likely to indicate a program error than a defensible +programming stratagem, SMARTALLOC disallows it with an assertion. + +When the standard library {\tt realloc()} function is called to expand a +buffer, it attempts to expand the buffer in place if possible, moving it only +if necessary. Because SMARTALLOC must place its own private storage in the +buffer and also to aid in error detection, its version of {\tt realloc()} +always moves and copies the buffer except in the trivial case where the size +of the buffer is not being changed. By forcing the buffer to move on every +call and destroying the contents of the old buffer when it is released, +SMARTALLOC traps programs which keep pointers into a buffer across a call on +{\tt realloc()} which may move it. This strategy may prove very costly to +programs which make extensive use of {\tt realloc()}. If this proves to be a +problem, such programs may wish to use {\tt actuallymalloc()}, {\tt +actuallyrealloc()}, and {\tt actuallyfree()} for such frequently-adjusted +buffers, trading error detection for performance. Although not specified in +the System V Interface Definition, many C library implementations of {\tt +realloc()} permit an old buffer argument of NULL, causing {\tt realloc()} to +allocate a new buffer. The SMARTALLOC version permits this. + +\subsection{ When SMARTALLOC is Disabled} +\index{When SMARTALLOC is Disabled } +\index{Disabled!When SMARTALLOC is } +\addcontentsline{toc}{subsection}{When SMARTALLOC is Disabled} + +When SMARTALLOC is disabled by compiling a program with the symbol SMARTALLOC +not defined, calls on the functions otherwise redefined by SMARTALLOC go +directly to the system functions. In addition, compile-time definitions +translate calls on the ''{\tt actually}...{\tt ()}`` functions into the +corresponding library calls; ''{\tt actuallymalloc(100)}``, for example, +compiles into ''{\tt malloc(100)}``. The two special SMARTALLOC functions, +{\tt sm\_dump()} and {\tt sm\_static()}, are defined to generate no code +(hence the null statement). Finally, if SMARTALLOC is not defined, compilation +of the file smartall.c generates no code or data at all, effectively removing +it from the program even if named in the link instructions. + +Thus, except for unusual circumstances, a program that works with SMARTALLOC +defined for testing should require no changes when built without it for +production release. + +\subsection{ The {\tt alloc()} Function} +\index{Function!alloc } +\index{Alloc() Function } +\addcontentsline{toc}{subsection}{alloc() Function} + +Many programs I've worked on use very few direct calls to {\tt malloc()}, +using the identically declared {\tt alloc()} function instead. Alloc detects +out-of-memory conditions and aborts, removing the need for error checking on +every call of {\tt malloc()} (and the temptation to skip checking for +out-of-memory). + +As a convenience, SMARTALLOC supplies a compatible version of {\tt alloc()} in +the file alloc.c, with its definition in the file alloc.h. This version of +{\tt alloc()} is sensitive to the definition of SMARTALLOC and cooperates with +SMARTALLOC's orphaned buffer detection. In addition, when SMARTALLOC is +defined and {\tt alloc()} detects an out of memory condition, it takes +advantage of the SMARTALLOC diagnostic information to identify the file and +line number of the call on {\tt alloc()} that failed. + +\subsection{ Overlays and Underhandedness} +\index{Underhandedness!Overlays and } +\index{Overlays and Underhandedness } +\addcontentsline{toc}{subsection}{Overlays and Underhandedness} + +String constants in the C language are considered to be static arrays of +characters accessed through a pointer constant. The arrays are potentially +writable even though their pointer is a constant. SMARTALLOC uses the +compile-time definition {\tt ./smartall.wml} to obtain the name of the file in +which a call on buffer allocation was performed. Rather than reserve space in +a buffer to save this information, SMARTALLOC simply stores the pointer to the +compiled-in text of the file name. This works fine as long as the program does +not overlay its data among modules. If data are overlayed, the area of memory +which contained the file name at the time it was saved in the buffer may +contain something else entirely when {\tt sm\_dump()} gets around to using the +pointer to edit the file name which allocated the buffer. + +If you want to use SMARTALLOC in a program with overlayed data, you'll have to +modify smartall.c to either copy the file name to a fixed-length field added +to the {\tt abufhead} structure, or else allocate storage with {\tt malloc()}, +copy the file name there, and set the {\tt abfname} pointer to that buffer, +then remember to release the buffer in {\tt sm\_free}. Either of these +approaches are wasteful of storage and time, and should be considered only if +there is no alternative. Since most initial debugging is done in non-overlayed +environments, the restrictions on SMARTALLOC with data overlaying may never +prove a problem. Note that conventional overlaying of code, by far the most +common form of overlaying, poses no problems for SMARTALLOC; you need only be +concerned if you're using exotic tools for data overlaying on MS-DOS or other +address-space-challenged systems. + +Since a C language ''constant`` string can actually be written into, most C +compilers generate a unique copy of each string used in a module, even if the +same constant string appears many times. In modules that contain many calls on +allocation functions, this results in substantial wasted storage for the +strings that identify the file name. If your compiler permits optimization of +multiple occurrences of constant strings, enabling this mode will eliminate +the overhead for these strings. Of course, it's up to you to make sure +choosing this compiler mode won't wreak havoc on some other part of your +program. + +\subsection{ Test and Demonstration Program} +\index{Test and Demonstration Program } +\index{Program!Test and Demonstration } +\addcontentsline{toc}{subsection}{Test and Demonstration Program} + +A test and demonstration program, smtest.c, is supplied with SMARTALLOC. You +can build this program with the Makefile included. Please refer to the +comments in smtest.c and the Makefile for information on this program. If +you're attempting to use SMARTALLOC on a new machine or with a new compiler or +operating system, it's a wise first step to check it out with smtest first. + +\subsection{ Invitation to the Hack} +\index{Hack!Invitation to the } +\index{Invitation to the Hack } +\addcontentsline{toc}{subsection}{Invitation to the Hack} + +SMARTALLOC is not intended to be a panacea for storage management problems, +nor is it universally applicable or effective; it's another weapon in the +arsenal of the defensive professional programmer attempting to create reliable +products. It represents the current state of evolution of expedient debug code +which has been used in several commercial software products which have, +collectively, sold more than third of a million copies in the retail market, +and can be expected to continue to develop through time as it is applied to +ever more demanding projects. + +The version of SMARTALLOC here has been tested on a Sun SPARCStation, Silicon +Graphics Indigo2, and on MS-DOS using both Borland and Microsoft C. Moving +from compiler to compiler requires the usual small changes to resolve disputes +about prototyping of functions, whether the type returned by buffer allocation +is {\tt char\ *} or {\tt void\ *}, and so forth, but following those changes +it works in a variety of environments. I hope you'll find SMARTALLOC as useful +for your projects as I've found it in mine. + +\section{ +\elink{}{http://www.fourmilab.ch/smartall/smartall.zip} +\elink{Download smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip} +(Zipped archive)} +\index{Archive! Download smartall.zip Zipped } +\index{ Download smartall.zip (Zipped archive) } +\addcontentsline{toc}{section}{ Download smartall.zip (Zipped archive)} + +SMARTALLOC is provided as +\elink{smartall.zip}{http://www.fourmilab.ch/smartall/smartall.zip}, a +\elink{Zipped}{http://www.pkware.com/} archive containing source code, +documentation, and a {\tt Makefile} to build the software under Unix. + +\subsection{ Copying} +\index{Copying } +\addcontentsline{toc}{subsection}{Copying} + +\begin{quote} +SMARTALLOC is in the public domain. Permission to use, copy, modify, and +distribute this software and its documentation for any purpose and without fee +is hereby granted, without any conditions or restrictions. This software is +provided ''as is`` without express or implied warranty. +\end{quote} + +{\it +\elink{by John Walker}{http://www.fourmilab.ch} +October 30th, 1998 } diff --git a/docs/manuals/fr/developers/storage.tex b/docs/manuals/fr/developers/storage.tex new file mode 100644 index 00000000..e46f228c --- /dev/null +++ b/docs/manuals/fr/developers/storage.tex @@ -0,0 +1,258 @@ +%% +%% + +\chapter{Storage Daemon Design} +\label{_ChapterStart3} +\index{Storage Daemon Design } +\index{Design!Storage Daemon } +\addcontentsline{toc}{section}{Storage Daemon Design} + +This chapter is intended to be a technical discussion of the Storage daemon +services and as such is not targeted at end users but rather at developers and +system administrators that want or need to know more of the working details of +{\bf Bacula}. + +This document is somewhat out of date. + +\section{SD Design Introduction} +\index{Introduction!SD Design } +\index{SD Design Introduction } +\addcontentsline{toc}{section}{SD Design Introduction} + +The Bacula Storage daemon provides storage resources to a Bacula installation. +An individual Storage daemon is associated with a physical permanent storage +device (for example, a tape drive, CD writer, tape changer or jukebox, etc.), +and may employ auxiliary storage resources (such as space on a hard disk file +system) to increase performance and/or optimize use of the permanent storage +medium. + +Any number of storage daemons may be run on a given machine; each associated +with an individual storage device connected to it, and BACULA operations may +employ storage daemons on any number of hosts connected by a network, local or +remote. The ability to employ remote storage daemons (with appropriate +security measures) permits automatic off-site backup, possibly to publicly +available backup repositories. + +\section{SD Development Outline} +\index{Outline!SD Development } +\index{SD Development Outline } +\addcontentsline{toc}{section}{SD Development Outline} + +In order to provide a high performance backup and restore solution that scales +to very large capacity devices and networks, the storage daemon must be able +to extract as much performance from the storage device and network with which +it interacts. In order to accomplish this, storage daemons will eventually +have to sacrifice simplicity and painless portability in favor of techniques +which improve performance. My goal in designing the storage daemon protocol +and developing the initial prototype storage daemon is to provide for these +additions in the future, while implementing an initial storage daemon which is +very simple and portable to almost any POSIX-like environment. This original +storage daemon (and its evolved descendants) can serve as a portable solution +for non-demanding backup requirements (such as single servers of modest size, +individual machines, or small local networks), while serving as the starting +point for development of higher performance configurable derivatives which use +techniques such as POSIX threads, shared memory, asynchronous I/O, buffering +to high-speed intermediate media, and support for tape changers and jukeboxes. + + +\section{SD Connections and Sessions} +\index{Sessions!SD Connections and } +\index{SD Connections and Sessions } +\addcontentsline{toc}{section}{SD Connections and Sessions} + +A client connects to a storage server by initiating a conventional TCP +connection. The storage server accepts the connection unless its maximum +number of connections has been reached or the specified host is not granted +access to the storage server. Once a connection has been opened, the client +may make any number of Query requests, and/or initiate (if permitted), one or +more Append sessions (which transmit data to be stored by the storage daemon) +and/or Read sessions (which retrieve data from the storage daemon). + +Most requests and replies sent across the connection are simple ASCII strings, +with status replies prefixed by a four digit status code for easier parsing. +Binary data appear in blocks stored and retrieved from the storage. Any +request may result in a single-line status reply of ``{\tt 3201\ Notification\ +pending}'', which indicates the client must send a ``Query notification'' +request to retrieve one or more notifications posted to it. Once the +notifications have been returned, the client may then resubmit the request +which resulted in the 3201 status. + +The following descriptions omit common error codes, yet to be defined, which +can occur from most or many requests due to events like media errors, +restarting of the storage daemon, etc. These details will be filled in, along +with a comprehensive list of status codes along with which requests can +produce them in an update to this document. + +\subsection{SD Append Requests} +\index{Requests!SD Append } +\index{SD Append Requests } +\addcontentsline{toc}{subsection}{SD Append Requests} + +\begin{description} + +\item [{append open session = \lt{}JobId\gt{} [ \lt{}Password\gt{} ] }] + \index{SPAN class } + A data append session is opened with the Job ID given by {\it JobId} with +client password (if required) given by {\it Password}. If the session is +successfully opened, a status of {\tt 3000\ OK} is returned with a ``{\tt +ticket\ =\ }{\it number}'' reply used to identify subsequent messages in the +session. If too many sessions are open, or a conflicting session (for +example, a read in progress when simultaneous read and append sessions are +not permitted), a status of ``{\tt 3502\ Volume\ busy}'' is returned. If no +volume is mounted, or the volume mounted cannot be appended to, a status of +``{\tt 3503\ Volume\ not\ mounted}'' is returned. + +\item [append data = \lt{}ticket-number\gt{} ] + \index{SPAN class } + If the append data is accepted, a status of {\tt 3000\ OK data address = +\lt{}IPaddress\gt{} port = \lt{}port\gt{}} is returned, where the {\tt +IPaddress} and {\tt port} specify the IP address and port number of the data +channel. Error status codes are {\tt 3504\ Invalid\ ticket\ number} and {\tt +3505\ Session\ aborted}, the latter of which indicates the entire append +session has failed due to a daemon or media error. + +Once the File daemon has established the connection to the data channel +opened by the Storage daemon, it will transfer a header packet followed by +any number of data packets. The header packet is of the form: + +{\tt \lt{}file-index\gt{} \lt{}stream-id\gt{} \lt{}info\gt{}} + +The details are specified in the +\ilink{Daemon Protocol}{_ChapterStart2} section of this +document. + +\item [*append abort session = \lt{}ticket-number\gt{} ] + \index{SPAN class } + The open append session with ticket {\it ticket-number} is aborted; any blocks +not yet written to permanent media are discarded. Subsequent attempts to +append data to the session will receive an error status of {\tt 3505\ +Session\ aborted}. + +\item [append end session = \lt{}ticket-number\gt{} ] + \index{SPAN class } + The open append session with ticket {\it ticket-number} is marked complete; no +further blocks may be appended. The storage daemon will give priority to +saving any buffered blocks from this session to permanent media as soon as +possible. + +\item [append close session = \lt{}ticket-number\gt{} ] + \index{SPAN class } + The append session with ticket {\it ticket} is closed. This message does not +receive an {\tt 3000\ OK} reply until all of the content of the session are +stored on permanent media, at which time said reply is given, followed by a +list of volumes, from first to last, which contain blocks from the session, +along with the first and last file and block on each containing session data +and the volume session key identifying data from that session in lines with +the following format: + +{\tt {\tt Volume = }\lt{}Volume-id\gt{} \lt{}start-file\gt{} +\lt{}start-block\gt{} \lt{}end-file\gt{} \lt{}end-block\gt{} +\lt{}volume-session-id\gt{}}where {\it Volume-id} is the volume label, {\it +start-file} and {\it start-block} are the file and block containing the first +data from that session on the volume, {\it end-file} and {\it end-block} are +the file and block with the last data from the session on the volume and {\it +volume-session-id} is the volume session ID for blocks from the session +stored on that volume. +\end{description} + +\subsection{SD Read Requests} +\index{SD Read Requests } +\index{Requests!SD Read } +\addcontentsline{toc}{subsection}{SD Read Requests} + +\begin{description} + +\item [Read open session = \lt{}JobId\gt{} \lt{}Volume-id\gt{} + \lt{}start-file\gt{} \lt{}start-block\gt{} \lt{}end-file\gt{} + \lt{}end-block\gt{} \lt{}volume-session-id\gt{} \lt{}password\gt{} ] +\index{SPAN class } +where {\it Volume-id} is the volume label, {\it start-file} and {\it +start-block} are the file and block containing the first data from that +session on the volume, {\it end-file} and {\it end-block} are the file and +block with the last data from the session on the volume and {\it +volume-session-id} is the volume session ID for blocks from the session +stored on that volume. + +If the session is successfully opened, a status of + +{\tt {\tt 3100\ OK Ticket\ =\ }{\it number}``} + +is returned with a reply used to identify subsequent messages in the session. +If too many sessions are open, or a conflicting session (for example, an +append in progress when simultaneous read and append sessions are not +permitted), a status of ''{\tt 3502\ Volume\ busy}`` is returned. If no +volume is mounted, or the volume mounted cannot be appended to, a status of +''{\tt 3503\ Volume\ not\ mounted}`` is returned. If no block with the given +volume session ID and the correct client ID number appears in the given first +file and block for the volume, a status of ''{\tt 3505\ Session\ not\ +found}`` is returned. + +\item [Read data = \lt{}Ticket\gt{} \gt{} \lt{}Block\gt{} ] + \index{SPAN class } + The specified Block of data from open read session with the specified Ticket +number is returned, with a status of {\tt 3000\ OK} followed by a ''{\tt +Length\ =\ }{\it size}`` line giving the length in bytes of the block data +which immediately follows. Blocks must be retrieved in ascending order, but +blocks may be skipped. If a block number greater than the largest stored on +the volume is requested, a status of ''{\tt 3201\ End\ of\ volume}`` is +returned. If a block number greater than the largest in the file is +requested, a status of ''{\tt 3401\ End\ of\ file}`` is returned. + +\item [Read close session = \lt{}Ticket\gt{} ] + \index{SPAN class } + The read session with Ticket number is closed. A read session may be closed +at any time; you needn't read all its blocks before closing it. +\end{description} + +{\it by +\elink{John Walker}{http://www.fourmilab.ch/} +January 30th, MM } + +\section{SD Data Structures} +\index{SD Data Structures} +\addcontentsline{toc}{section}{SD Data Structures} + +In the Storage daemon, there is a Device resource (i.e. from conf file) +that describes each physical device. When the physical device is used it +is controled by the DEVICE structure (defined in dev.h), and typically +refered to as dev in the C++ code. Anyone writing or reading a physical +device must ultimately get a lock on the DEVICE structure -- this controls +the device. However, multiple Jobs (defined by a JCR structure src/jcr.h) +can be writing a physical DEVICE at the same time (of course they are +sequenced by locking the DEVICE structure). There are a lot of job +dependent "device" variables that may be different for each Job such as +spooling (one job may spool and another may not, and when a job is +spooling, it must have an i/o packet open, each job has its own record and +block structures, ...), so there is a device control record or DCR that is +the primary way of interfacing to the physical device. The DCR contains +all the job specific data as well as a pointer to the Device resource +(DEVRES structure) and the physical DEVICE structure. + +Now if a job is writing to two devices (it could be writing two separate +streams to the same device), it must have two DCRs. Today, the code only +permits one. This won't be hard to change, but it is new code. + +Today three jobs (threads), two physical devices each job + writes to only one device: + +\begin{verbatim} + Job1 -> DCR1 -> DEVICE1 + Job2 -> DCR2 -> DEVICE1 + Job3 -> DCR3 -> DEVICE2 +\end{verbatim} + +To be implemented three jobs, three physical devices, but + job1 is writing simultaneously to three devices: + +\begin{verbatim} + Job1 -> DCR1 -> DEVICE1 + -> DCR4 -> DEVICE2 + -> DCR5 -> DEVICE3 + Job2 -> DCR2 -> DEVICE1 + Job3 -> DCR3 -> DEVICE2 + + Job = job control record + DCR = Job contorl data for a specific device + DEVICE = Device only control data +\end{verbatim} + diff --git a/docs/manuals/fr/developers/tls-techdoc.tex b/docs/manuals/fr/developers/tls-techdoc.tex new file mode 100644 index 00000000..565869f1 --- /dev/null +++ b/docs/manuals/fr/developers/tls-techdoc.tex @@ -0,0 +1,391 @@ +%% +%% + +%\author{Landon Fuller} +%\title{Bacula TLS Additions} + +\chapter{TLS} +\label{_Chapter_TLS} +\index{TLS} + +Written by Landon Fuller + +\section{Introduction to TLS} +\index{TLS Introduction} +\index{Introduction!TLS} +\addcontentsline{toc}{section}{TLS Introduction} + +This patch includes all the back-end code necessary to add complete TLS +data encryption support to Bacula. In addition, support for TLS in +Console/Director communications has been added as a proof of concept. +Adding support for the remaining daemons will be straight-forward. +Supported features of this patchset include: + +\begin{itemize} +\item Client/Server TLS Requirement Negotiation +\item TLSv1 Connections with Server and Client Certificate +Validation +\item Forward Secrecy Support via Diffie-Hellman Ephemeral Keying +\end{itemize} + +This document will refer to both ``server'' and ``client'' contexts. These +terms refer to the accepting and initiating peer, respectively. + +Diffie-Hellman anonymous ciphers are not supported by this patchset. The +use of DH anonymous ciphers increases the code complexity and places +explicit trust upon the two-way Cram-MD5 implementation. Cram-MD5 is +subject to known plaintext attacks, and is should be considered +considerably less secure than PKI certificate-based authentication. + +Appropriate autoconf macros have been added to detect and use OpenSSL. Two +additional preprocessor defines have been added: \emph{HAVE\_TLS} and +\emph{HAVE\_OPENSSL}. All changes not specific to OpenSSL rely on +\emph{HAVE\_TLS}. OpenSSL-specific code is constrained to +\emph{src/lib/tls.c} to facilitate the support of alternative TLS +implementations. + +\section{New Configuration Directives} +\index{TLS Configuration Directives} +\index{Directives!TLS Configuration} +\addcontentsline{toc}{section}{New Configuration Directives} + +Additional configuration directives have been added to both the Console and +Director resources. These new directives are defined as follows: + +\begin{itemize} +\item \underline{TLS Enable} \emph{(yes/no)} +Enable TLS support. + +\item \underline{TLS Require} \emph{(yes/no)} +Require TLS connections. + +\item \underline{TLS Certificate} \emph{(path)} +Path to PEM encoded TLS certificate. Used as either a client or server +certificate. + +\item \underline{TLS Key} \emph{(path)} +Path to PEM encoded TLS private key. Must correspond with the TLS +certificate. + +\item \underline{TLS Verify Peer} \emph{(yes/no)} +Verify peer certificate. Instructs server to request and verify the +client's x509 certificate. Any client certificate signed by a known-CA +will be accepted unless the TLS Allowed CN configuration directive is used. +Not valid in a client context. + +\item \underline{TLS Allowed CN} \emph{(string list)} +Common name attribute of allowed peer certificates. If directive is +specified, all client certificates will be verified against this list. +This directive may be specified more than once. Not valid in a client +context. + +\item \underline{TLS CA Certificate File} \emph{(path)} +Path to PEM encoded TLS CA certificate(s). Multiple certificates are +permitted in the file. One of \emph{TLS CA Certificate File} or \emph{TLS +CA Certificate Dir} are required in a server context if \underline{TLS +Verify Peer} is also specified, and are always required in a client +context. + +\item \underline{TLS CA Certificate Dir} \emph{(path)} +Path to TLS CA certificate directory. In the current implementation, +certificates must be stored PEM encoded with OpenSSL-compatible hashes. +One of \emph{TLS CA Certificate File} or \emph{TLS CA Certificate Dir} are +required in a server context if \emph{TLS Verify Peer} is also specified, +and are always required in a client context. + +\item \underline{TLS DH File} \emph{(path)} +Path to PEM encoded Diffie-Hellman parameter file. If this directive is +specified, DH ephemeral keying will be enabled, allowing for forward +secrecy of communications. This directive is only valid within a server +context. To generate the parameter file, you may use openssl: +\footnotesize +\begin{verbatim} +openssl dhparam -out dh1024.pem -5 1024 +\end{verbatim} +\normalsize +\end{itemize} + +\section{TLS API Implementation} +\index{TLS API Implimentation} +\index{API Implimentation!TLS} +\addcontentsline{toc}{section}{TLS API Implementation} + +To facilitate the use of additional TLS libraries, all OpenSSL-specific +code has been implemented within \emph{src/lib/tls.c}. In turn, a generic +TLS API is exported. + +\subsection{Library Initialization and Cleanup} +\index{Library Initialization and Cleanup} +\index{Initialization and Cleanup!Library} +\addcontentsline{toc}{subsection}{Library Initialization and Cleanup} + +\footnotesize +\begin{verbatim} +int init_tls (void); +\end{verbatim} +\normalsize + +Performs TLS library initialization, including seeding of the PRNG. PRNG +seeding has not yet been implemented for win32. + +\footnotesize +\begin{verbatim} +int cleanup_tls (void); +\end{verbatim} +\normalsize + +Performs TLS library cleanup. + +\subsection{Manipulating TLS Contexts} +\index{TLS Context Manipulation} +\index{Contexts!Manipulating TLS} +\addcontentsline{toc}{subsection}{Manipulating TLS Contexts} + +\footnotesize +\begin{verbatim} +TLS_CONTEXT *new_tls_context (const char *ca_certfile, + const char *ca_certdir, const char *certfile, + const char *keyfile, const char *dhfile, bool verify_peer); +\end{verbatim} +\normalsize + +Allocates and initalizes a new opaque \emph{TLS\_CONTEXT} structure. The +\emph{TLS\_CONTEXT} structure maintains default TLS settings from which +\emph{TLS\_CONNECTION} structures are instantiated. In the future the +\emph{TLS\_CONTEXT} structure may be used to maintain the TLS session +cache. \emph{ca\_certfile} and \emph{ca\_certdir} arguments are used to +initialize the CA verification stores. The \emph{certfile} and +\emph{keyfile} arguments are used to initialize the local certificate and +private key. If \emph{dhfile} is non-NULL, it is used to initialize +Diffie-Hellman ephemeral keying. If \emph{verify\_peer} is \emph{true} , +client certificate validation is enabled. + +\footnotesize +\begin{verbatim} +void free_tls_context (TLS_CONTEXT *ctx); +\end{verbatim} +\normalsize + +Deallocated a previously allocated \emph{TLS\_CONTEXT} structure. + +\subsection{Performing Post-Connection Verification} +\index{TLS Post-Connection Verification} +\index{Verification!TLS Post-Connection} +\addcontentsline{toc}{subsection}{Performing Post-Connection Verification} + +\footnotesize +\begin{verbatim} +bool tls_postconnect_verify_host (TLS_CONNECTION *tls, const char *host); +\end{verbatim} +\normalsize + +Performs post-connection verification of the peer-supplied x509 +certificate. Checks whether the \emph{subjectAltName} and +\emph{commonName} attributes match the supplied \emph{host} string. +Returns \emph{true} if there is a match, \emph{false} otherwise. + +\footnotesize +\begin{verbatim} +bool tls_postconnect_verify_cn (TLS_CONNECTION *tls, alist *verify_list); +\end{verbatim} +\normalsize + +Performs post-connection verification of the peer-supplied x509 +certificate. Checks whether the \emph{commonName} attribute matches any +strings supplied via the \emph{verify\_list} parameter. Returns +\emph{true} if there is a match, \emph{false} otherwise. + +\subsection{Manipulating TLS Connections} +\index{TLS Connection Manipulation} +\index{Connections!Manipulating TLS} +\addcontentsline{toc}{subsection}{Manipulating TLS Connections} + +\footnotesize +\begin{verbatim} +TLS_CONNECTION *new_tls_connection (TLS_CONTEXT *ctx, int fd); +\end{verbatim} +\normalsize + +Allocates and initializes a new \emph{TLS\_CONNECTION} structure with +context \emph{ctx} and file descriptor \emph{fd}. + +\footnotesize +\begin{verbatim} +void free_tls_connection (TLS_CONNECTION *tls); +\end{verbatim} +\normalsize + +Deallocates memory associated with the \emph{tls} structure. + +\footnotesize +\begin{verbatim} +bool tls_bsock_connect (BSOCK *bsock); +\end{verbatim} +\normalsize + +Negotiates a a TLS client connection via \emph{bsock}. Returns \emph{true} +if successful, \emph{false} otherwise. Will fail if there is a TLS +protocol error or an invalid certificate is presented + +\footnotesize +\begin{verbatim} +bool tls_bsock_accept (BSOCK *bsock); +\end{verbatim} +\normalsize + +Accepts a TLS client connection via \emph{bsock}. Returns \emph{true} if +successful, \emph{false} otherwise. Will fail if there is a TLS protocol +error or an invalid certificate is presented. + +\footnotesize +\begin{verbatim} +bool tls_bsock_shutdown (BSOCK *bsock); +\end{verbatim} +\normalsize + +Issues a blocking TLS shutdown request to the peer via \emph{bsock}. This function may not wait for the peer's reply. + +\footnotesize +\begin{verbatim} +int tls_bsock_writen (BSOCK *bsock, char *ptr, int32_t nbytes); +\end{verbatim} +\normalsize + +Writes \emph{nbytes} from \emph{ptr} via the \emph{TLS\_CONNECTION} +associated with \emph{bsock}. Due to OpenSSL's handling of \emph{EINTR}, +\emph{bsock} is set non-blocking at the start of the function, and restored +to its original blocking state before the function returns. Less than +\emph{nbytes} may be written if an error occurs. The actual number of +bytes written will be returned. + +\footnotesize +\begin{verbatim} +int tls_bsock_readn (BSOCK *bsock, char *ptr, int32_t nbytes); +\end{verbatim} +\normalsize + +Reads \emph{nbytes} from the \emph{TLS\_CONNECTION} associated with +\emph{bsock} and stores the result in \emph{ptr}. Due to OpenSSL's +handling of \emph{EINTR}, \emph{bsock} is set non-blocking at the start of +the function, and restored to its original blocking state before the +function returns. Less than \emph{nbytes} may be read if an error occurs. +The actual number of bytes read will be returned. + +\section{Bnet API Changes} +\index{Bnet API Changes} +\index{API Changes!Bnet} +\addcontentsline{toc}{section}{Bnet API Changes} + +A minimal number of changes were required in the Bnet socket API. The BSOCK +structure was expanded to include an associated TLS\_CONNECTION structure, +as well as a flag to designate the current blocking state of the socket. +The blocking state flag is required for win32, where it does not appear +possible to discern the current blocking state of a socket. + +\subsection{Negotiating a TLS Connection} +\index{Negotiating a TLS Connection} +\index{TLS Connection!Negotiating} +\addcontentsline{toc}{subsection}{Negotiating a TLS Connection} + +\emph{bnet\_tls\_server()} and \emph{bnet\_tls\_client()} were both +implemented using the new TLS API as follows: + +\footnotesize +\begin{verbatim} +int bnet_tls_client(TLS_CONTEXT *ctx, BSOCK * bsock); +\end{verbatim} +\normalsize + +Negotiates a TLS session via \emph{bsock} using the settings from +\emph{ctx}. Returns 1 if successful, 0 otherwise. + +\footnotesize +\begin{verbatim} +int bnet_tls_server(TLS_CONTEXT *ctx, BSOCK * bsock, alist *verify_list); +\end{verbatim} +\normalsize + +Accepts a TLS client session via \emph{bsock} using the settings from +\emph{ctx}. If \emph{verify\_list} is non-NULL, it is passed to +\emph{tls\_postconnect\_verify\_cn()} for client certificate verification. + +\subsection{Manipulating Socket Blocking State} +\index{Manipulating Socket Blocking State} +\index{Socket Blocking State!Manipulating} +\index{Blocking State!Socket!Manipulating} +\addcontentsline{toc}{subsection}{Manipulating Socket Blocking State} + +Three functions were added for manipulating the blocking state of a socket +on both Win32 and Unix-like systems. The Win32 code was written according +to the MSDN documentation, but has not been tested. + +These functions are prototyped as follows: + +\footnotesize +\begin{verbatim} +int bnet_set_nonblocking (BSOCK *bsock); +\end{verbatim} +\normalsize + +Enables non-blocking I/O on the socket associated with \emph{bsock}. +Returns a copy of the socket flags prior to modification. + +\footnotesize +\begin{verbatim} +int bnet_set_blocking (BSOCK *bsock); +\end{verbatim} +\normalsize + +Enables blocking I/O on the socket associated with \emph{bsock}. Returns a +copy of the socket flags prior to modification. + +\footnotesize +\begin{verbatim} +void bnet_restore_blocking (BSOCK *bsock, int flags); +\end{verbatim} +\normalsize + +Restores blocking or non-blocking IO setting on the socket associated with +\emph{bsock}. The \emph{flags} argument must be the return value of either +\emph{bnet\_set\_blocking()} or \emph{bnet\_restore\_blocking()}. + +\pagebreak + +\section{Authentication Negotiation} +\index{Authentication Negotiation} +\index{Negotiation!TLS Authentication} +\addcontentsline{toc}{section}{Authentication Negotiation} + +Backwards compatibility with the existing SSL negotiation hooks implemented +in src/lib/cram-md5.c have been maintained. The +\emph{cram\_md5\_get\_auth()} function has been modified to accept an +integer pointer argument, tls\_remote\_need. The TLS requirement +advertised by the remote host is returned via this pointer. + +After exchanging cram-md5 authentication and TLS requirements, both the +client and server independently decide whether to continue: + +\footnotesize +\begin{verbatim} +if (!cram_md5_get_auth(dir, password, &tls_remote_need) || + !cram_md5_auth(dir, password, tls_local_need)) { +[snip] +/* Verify that the remote host is willing to meet our TLS requirements */ +if (tls_remote_need < tls_local_need && tls_local_need != BNET_TLS_OK && + tls_remote_need != BNET_TLS_OK) { + sendit(_("Authorization problem:" + " Remote server did not advertise required TLS support.\n")); + auth_success = false; + goto auth_done; +} + +/* Verify that we are willing to meet the remote host's requirements */ +if (tls_remote_need > tls_local_need && tls_local_need != BNET_TLS_OK && + tls_remote_need != BNET_TLS_OK) { + sendit(_("Authorization problem:" + " Remote server requires TLS.\n")); + auth_success = false; + goto auth_done; +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/developers/translate_images.pl b/docs/manuals/fr/developers/translate_images.pl new file mode 100755 index 00000000..c7225118 --- /dev/null +++ b/docs/manuals/fr/developers/translate_images.pl @@ -0,0 +1,185 @@ +#!/usr/bin/perl -w +# +use strict; + +# Used to change the names of the image files generated by latex2html from imgxx.png +# to meaningful names. Provision is made to go either from or to the meaningful names. +# The meaningful names are obtained from a file called imagename_translations, which +# is generated by extensions to latex2html in the make_image_file subroutine in +# bacula.perl. + +# Opens the file imagename_translations and reads the contents into a hash. +# The hash is creaed with the imgxx.png files as the key if processing TO +# meaningful filenames, and with the meaningful filenames as the key if +# processing FROM meaningful filenames. +# Then opens the html file(s) indicated in the command-line arguments and +# changes all image references according to the translations described in the +# above file. Finally, it renames the image files. +# +# Original creation: 3-27-05 by Karl Cunningham. +# Modified 5-21-05 to go FROM and TO meaningful filenames. +# +my $TRANSFILE = "imagename_translations"; +my $path; + +# Loads the contents of $TRANSFILE file into the hash referenced in the first +# argument. The hash is loaded to translate old to new if $direction is 0, +# otherwise it is loaded to translate new to old. In this context, the +# 'old' filename is the meaningful name, and the 'new' filename is the +# imgxx.png filename. It is assumed that the old image is the one that +# latex2html has used as the source to create the imgxx.png filename. +# The filename extension is taken from the file +sub read_transfile { + my ($trans,$direction) = @_; + + if (!open IN,"<$path$TRANSFILE") { + print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n"; + print " Image filename translation aborted\n\n"; + exit 0; + } + + while () { + chomp; + my ($new,$old) = split(/\001/); + + # Old filenames will usually have a leading ./ which we don't need. + $old =~ s/^\.\///; + + # The filename extension of the old filename must be made to match + # the new filename because it indicates the encoding format of the image. + my ($ext) = $new =~ /(\.[^\.]*)$/; + $old =~ s/\.[^\.]*$/$ext/; + if ($direction == 0) { + $trans->{$new} = $old; + } else { + $trans->{$old} = $new; + } + } + close IN; +} + +# Translates the image names in the file given as the first argument, according to +# the translations in the hash that is given as the second argument. +# The file contents are read in entirely into a string, the string is processed, and +# the file contents are then written. No particular care is taken to ensure that the +# file is not lost if a system failure occurs at an inopportune time. It is assumed +# that the html files being processed here can be recreated on demand. +# +# Links to other files are added to the %filelist for processing. That way, +# all linked files will be processed (assuming they are local). +sub translate_html { + my ($filename,$trans,$filelist) = @_; + my ($contents,$out,$this,$img,$dest); + my $cnt = 0; + + # If the filename is an external link ignore it. And drop any file:// from + # the filename. + $filename =~ /^(http|ftp|mailto)\:/ and return 0; + $filename =~ s/^file\:\/\///; + # Load the contents of the html file. + if (!open IF,"<$path$filename") { + print "WARNING: Cannot open $path$filename for reading\n"; + print " Image Filename Translation aborted\n\n"; + exit 0; + } + + while () { + $contents .= $_; + } + close IF; + + # Now do the translation... + # First, search for an image filename. + while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) { + $contents = $'; + $out .= $` . $&; + + # The next thing is an image name. Get it and translate it. + $contents =~ /^(.*?)\"/s; + $contents = $'; + $this = $&; + $img = $1; + # If the image is in our list of ones to be translated, do it + # and feed the result to the output. + $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img})); + $out .= $this; + } + $out .= $contents; + + # Now send the translated text to the html file, overwriting what's there. + open OF,">$path$filename" or die "Cannot open $path$filename for writing\n"; + print OF $out; + close OF; + + # Now look for any links to other files and add them to the list of files to do. + while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) { + $out = $'; + $dest = $1; + # Drop an # and anything after it. + $dest =~ s/\#.*//; + $filelist->{$dest} = '' if $dest; + } + return $cnt; +} + +# REnames the image files spefified in the %translate hash. +sub rename_images { + my $translate = shift; + my ($response); + + foreach (keys(%$translate)) { + if (! $translate->{$_}) { + print " WARNING: No destination Filename for $_\n"; + } else { + $response = `mv -f $path$_ $path$translate->{$_} 2>&1`; + $response and print "ERROR from system $response\n"; + } + } +} + +################################################# +############# MAIN ############################# +################################################ + +# %filelist starts out with keys from the @ARGV list. As files are processed, +# any links to other files are added to the %filelist. A hash of processed +# files is kept so we don't do any twice. + +# The first argument must be either --to_meaningful_names or --from_meaningful_names + +my (%translate,$search_regex,%filelist,%completed,$thisfile); +my ($cnt,$direction); + +my $arg0 = shift(@ARGV); +$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or + die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n"; + +$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1; + +(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n"; + +# Use the first argument to get the path to the file of translations. +my $tmp = $ARGV[0]; +($path) = $tmp =~ /(.*\/)/; +$path = '' unless $path; + +read_transfile(\%translate,$direction); + +foreach (@ARGV) { + # Strip the path from the filename, and use it later on. + if (s/(.*\/)//) { + $path = $1; + } else { + $path = ''; + } + $filelist{$_} = ''; + + while ($thisfile = (keys(%filelist))[0]) { + $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile})); + delete($filelist{$thisfile}); + $completed{$thisfile} = ''; + } + print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n"; +} + +rename_images(\%translate); diff --git a/docs/manuals/fr/developers/update_version b/docs/manuals/fr/developers/update_version new file mode 100755 index 00000000..5c2e0092 --- /dev/null +++ b/docs/manuals/fr/developers/update_version @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/developers/update_version.in b/docs/manuals/fr/developers/update_version.in new file mode 100644 index 00000000..2766245f --- /dev/null +++ b/docs/manuals/fr/developers/update_version.in @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/developers/version.tex b/docs/manuals/fr/developers/version.tex new file mode 100644 index 00000000..82d910aa --- /dev/null +++ b/docs/manuals/fr/developers/version.tex @@ -0,0 +1 @@ +2.3.6 (04 November 2007) diff --git a/docs/manuals/fr/developers/version.tex.in b/docs/manuals/fr/developers/version.tex.in new file mode 100644 index 00000000..ff66dfc6 --- /dev/null +++ b/docs/manuals/fr/developers/version.tex.in @@ -0,0 +1 @@ +@VERSION@ (@DATE@) diff --git a/docs/manuals/fr/install/Makefile b/docs/manuals/fr/install/Makefile new file mode 100644 index 00000000..0edc87f6 --- /dev/null +++ b/docs/manuals/fr/install/Makefile @@ -0,0 +1,139 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=install + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null + makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null + makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null + makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Installation and Configuration Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Instal_Config_Guide.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/install/Makefile.in b/docs/manuals/fr/install/Makefile.in new file mode 100644 index 00000000..0edc87f6 --- /dev/null +++ b/docs/manuals/fr/install/Makefile.in @@ -0,0 +1,139 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=install + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + makeindex ${DOC}.ddx -o ${DOC}.dnd >/dev/null 2>/dev/null + makeindex ${DOC}.fdx -o ${DOC}.fnd >/dev/null 2>/dev/null + makeindex ${DOC}.sdx -o ${DOC}.snd >/dev/null 2>/dev/null + makeindex ${DOC}.cdx -o ${DOC}.cnd >/dev/null 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Installation and Configuration Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Instal_Config_Guide.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/install/Makefile.save b/docs/manuals/fr/install/Makefile.save new file mode 100644 index 00000000..8a1708ab --- /dev/null +++ b/docs/manuals/fr/install/Makefile.save @@ -0,0 +1,101 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# + +IMAGES=../../../images + +first_rule: bacula + +bacula: tex web html dvipdf + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @cp -fp ${IMAGES}/hires/*.eps . + touch install.idx installi-general.tex + -latex -interaction=batchmode install.tex + makeindex install.idx >/dev/null 2>/dev/null + -latex -interaction=batchmode install.tex + +pdf: + @echo "Making install pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf install.dvi install.pdf + @rm -f *.eps *.old + +dvipdf: + @echo "Making install pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 install.dvi + @rm -f *.eps *.old + +html: + @echo "Making install html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names install.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + install >/dev/null + ./translate_images.pl --to_meaningful_names install.html + @rm -f *.eps *.gif *.jpg *.old + +web: + @echo "Making install web" + @mkdir -p install + @rm -f install/* + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png install/ + @rm -f install/next.eps install/next.png install/prev.eps install/prev.png install/up.eps install/up.png + @(if [ -f install/imagename_translations ] ; then \ + ./translate_images.pl --to_meaningful_names install/Bacula_Users_Guide.html; \ + fi) + @rm -rf install/*.html + latex2html -split 3 -local_icons -t "Developer's Guide" \ + -long_titles 4 -contents_in_nav -toc_stars -white \ + -notransparent install >/dev/null + ./translate_images.pl --to_meaningful_names install/install_Guide.html + @cp -f install/install_Guide.html install/index.html + @rm -f *.eps *.gif *.jpg install/*.eps *.old + @rm -f install/idle.png + @rm -f install/win32-*.png install/wx-console*.png install/xp-*.png + @rm -f install/*.pl install/*.log install/*.aux install/*.idx + @rm -f install/*.out WARNINGS + +texcheck: + ./check_tex.pl install.tex + +main_configs: + pic2graph -density 100 main_configs.png + +clean: + @rm -f 1 2 3 + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.pdf *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f images.pl labels.pl internals.pl + @rm -rf install + @rm -f images.tex installi-general.tex + + +distclean: clean + @rm -f install.html install.pdf diff --git a/docs/manuals/fr/install/autochangerres.tex b/docs/manuals/fr/install/autochangerres.tex new file mode 100644 index 00000000..98563c77 --- /dev/null +++ b/docs/manuals/fr/install/autochangerres.tex @@ -0,0 +1,107 @@ +%% +\chapter{Autochanger Resource} +\index[sd]{Autochanger Resource} +\index[sd]{Resource!Autochanger} + +The Autochanger resource supports single or multiple drive +autochangers by grouping one or more Device resources +into one unit called an autochanger in Bacula (often referred to +as a "tape library" by autochanger manufacturers). + +If you have an Autochanger, and you want it to function correctly, +you {\bf must} have an Autochanger resource in your Storage +conf file, and your Director's Storage directives that want to +use an Autochanger {\bf must} refer to the Autochanger resource name. +In previous versions of Bacula, the Director's Storage directives +referred directly to Device resources that were autochangers. +In version 1.38.0 and later, referring directly to Device resources +will not work for Autochangers. + +\begin{description} +\item [Name = \lt{}Autochanger-Name\gt{}] + \index[sd]{Name} + Specifies the Name of the Autochanger. This name is used in the + Director's Storage definition to refer to the autochanger. This + directive is required. + +\item [Device = \lt{}Device-name1, device-name2, ...\gt{}] + Specifies the names of the Device resource or resources that correspond + to the autochanger drive. If you have a multiple drive autochanger, you + must specify multiple Device names, each one referring to a separate + Device resource that contains a Drive Index specification that + corresponds to the drive number base zero. You may specify multiple + device names on a single line separated by commas, and/or you may + specify multiple Device directives. This directive is required. + +\item [Changer Device = {\it name-string}] + \index[sd]{Changer Device} + The specified {\bf name-string} gives the system file name of the autochanger + device name. If specified in this resource, the Changer Device name + is not needed in the Device resource. If it is specified in the Device + resource (see above), it will take precedence over one specified in + the Autochanger resource. + +\item [Changer Command = {\it name-string}] + \index[sd]{Changer Command } + The {\bf name-string} specifies an external program to be called that will + automatically change volumes as required by {\bf Bacula}. Most frequently, + you will specify the Bacula supplied {\bf mtx-changer} script as follows. + If it is specified here, it need not be specified in the Device + resource. If it is also specified in the Device resource, it will take + precedence over the one specified in the Autochanger resource. + +\end{description} + +The following is an example of a valid Autochanger resource definition: + +\footnotesize +\begin{verbatim} +Autochanger { + Name = "DDS-4-changer" + Device = DDS-4-1, DDS-4-2, DDS-4-3 + Changer Device = /dev/sg0 + Changer Command = "/etc/bacula/mtx-changer %c %o %S %a %d" +} +Device { + Name = "DDS-4-1" + Drive Index = 0 + Autochanger = yes + ... +} +Device { + Name = "DDS-4-2" + Drive Index = 1 + Autochanger = yes + ... +Device { + Name = "DDS-4-3" + Drive Index = 2 + Autochanger = yes + Autoselect = no + ... +} +\end{verbatim} +\normalsize + +Please note that it is important to include the {\bf Autochanger = yes} directive +in each Device definition that belongs to an Autochanger. A device definition +should not belong to more than one Autochanger resource. Also, your Device +directive in the Storage resource of the Director's conf file should have +the Autochanger's resource name rather than a name of one of the Devices. + +If you have a drive that physically belongs to an Autochanger but you don't want +to have it automatically used when Bacula references the Autochanger for backups, +for example, you want to reserve it for restores, you can add the directive: + +\footnotesize +\begin{verbatim} +Autoselect = no +\end{verbatim} +\normalsize + +to the Device resource for that drive. In that case, Bacula will not automatically +select that drive when accessing the Autochanger. You can, still use the drive +by referencing it by the Device name directly rather than the Autochanger name. An example +of such a definition is shown above for the Device DDS-4-3, which will not be +selected when the name DDS-4-changer is used in a Storage definition, but will +be used if DDS-4-3 is used. diff --git a/docs/manuals/fr/install/check_tex.pl b/docs/manuals/fr/install/check_tex.pl new file mode 100755 index 00000000..e12d51be --- /dev/null +++ b/docs/manuals/fr/install/check_tex.pl @@ -0,0 +1,152 @@ +#!/usr/bin/perl -w +# Finds potential problems in tex files, and issues warnings to the console +# about what it finds. Takes a list of files as its only arguments, +# and does checks on all the files listed. The assumption is that these are +# valid (or close to valid) LaTeX files. It follows \include statements +# recursively to pick up any included tex files. +# +# +# +# Currently the following checks are made: +# +# -- Multiple hyphens not inside a verbatim environment (or \verb). These +# should be placed inside a \verb{} contruct so they will not be converted +# to single hyphen by latex and latex2html. + + +# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com +# +# + +use strict; + +# The following builds the test string to identify and change multiple +# hyphens in the tex files. Several constructs are identified but only +# multiple hyphens are changed; the others are fed to the output +# unchanged. +my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{ +my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{ +my $c = '\\s*\\}'; # closing curly brace + +# This captures entire verbatim environments. These are passed to the output +# file unchanged. +my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c; + +# This captures \verb{..{ constructs. They are passed to the output unchanged. +my $verb = '\\\\verb\\*?(.).*?\\1'; + +# This captures multiple hyphens with a leading and trailing space. These are not changed. +my $hyphsp = '\\s\\-{2,}\\s'; + +# This identifies other multiple hyphens. +my $hyphens = '\\-{2,}'; + +# This identifies \hyperpage{..} commands, which should be ignored. +my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}'; + +# This builds the actual test string from the above strings. +#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens"; +my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens"; + + +sub get_includes { + # Get a list of include files from the top-level tex file. The first + # argument is a pointer to the list of files found. The rest of the + # arguments is a list of filenames to check for includes. + my $files = shift; + my ($fileline,$includefile,$includes); + + while (my $filename = shift) { + # Get a list of all the html files in the directory. + open my $if,"<$filename" or die "Cannot open input file $filename\n"; + $fileline = 0; + $includes = 0; + while (<$if>) { + chomp; + $fileline++; + # If a file is found in an include, process it. + if (($includefile) = /\\include\s*\{(.*?)\}/) { + $includes++; + # Append .tex to the filename + $includefile .= '.tex'; + + # If the include file has already been processed, issue a warning + # and don't do it again. + my $found = 0; + foreach (@$files) { + if ($_ eq $includefile) { + $found = 1; + last; + } + } + if ($found) { + print "$includefile found at line $fileline in $filename was previously included\n"; + } else { + # The file has not been previously found. Save it and + # recursively process it. + push (@$files,$includefile); + get_includes($files,$includefile); + } + } + } + close IF; + } +} + + +sub check_hyphens { + my (@files) = @_; + my ($filedata,$this,$linecnt,$before); + + # Build the test string to check for the various environments. + # We only do the conversion if the multiple hyphens are outside of a + # verbatim environment (either \begin{verbatim}...\end{verbatim} or + # \verb{--}). Capture those environments and pass them to the output + # unchanged. + + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # Set up to process the file data. + $linecnt = 1; + + # Go through the file data from beginning to end. For each match, save what + # came before it and what matched. $filedata now becomes only what came + # after the match. + # Chech the match to see if it starts with a multiple-hyphen. If so + # warn the user. Keep track of line numbers so they can be output + # with the warning message. + while ($filedata =~ /$teststr/os) { + $this = $&; + $before = $`; + $filedata = $'; + $linecnt += $before =~ tr/\n/\n/; + + # Check if the multiple hyphen is present outside of one of the + # acceptable constructs. + if ($this =~ /^\-+/) { + print "Possible unwanted multiple hyphen found in line ", + "$linecnt of file $file\n"; + } + $linecnt += $this =~ tr/\n/\n/; + } + } +} +################################################################## +# MAIN #### +################################################################## + +my (@includes,$cnt); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +get_includes(\@includes,@ARGV); + +check_hyphens(@includes); diff --git a/docs/manuals/fr/install/configure.tex b/docs/manuals/fr/install/configure.tex new file mode 100644 index 00000000..e37773b9 --- /dev/null +++ b/docs/manuals/fr/install/configure.tex @@ -0,0 +1,408 @@ +%% +%% + +\chapter{Customizing the Configuration Files} +\label{ConfigureChapter} +\index[general]{Files!Customizing the Configuration } +\index[general]{Customizing the Configuration Files } + +When each of the Bacula programs starts, it reads a configuration file +specified on the command line or the default {\bf bacula-dir.conf}, {\bf +bacula-fd.conf}, {\bf bacula-sd.conf}, or {\bf console.conf} for the Director +daemon, the File daemon, the Storage daemon, and the Console program +respectively. + +Each service (Director, Client, Storage, Console) has its own configuration +file containing a set of Resource definitions. These resources are very +similar from one service to another, but may contain different directives +(records) depending on the service. For example, in the Director's resource +file, the {\bf Director} resource defines the name of the Director, a number +of global Director parameters and his password. In the File daemon +configuration file, the {\bf Director} resource specifies which Directors are +permitted to use the File daemon. + +Before running Bacula for the first time, you must customize the configuration +files for each daemon. Default configuration files will have been created by +the installation process, but you will need to modify them to correspond to +your system. An overall view of the resources can be seen in the following: + +\addcontentsline{lof}{figure}{Bacula Objects} +\includegraphics{./bacula-objects.eps} +\\ +(thanks to Aristides Maniatis for the above graphic) +\label{ResFormat} + +\section{Character Sets} +\index[general]{Character Sets} +Bacula is designed to handle most character sets of the world, +US ASCII, German, French, Chinese, ... However, it does this by +encoding everything in UTF-8, and it expects all configuration files +(including those read on Win32 machines) to be in UTF-8 format. +UTF-8 is typically the default on Linux machines, but not on all +Unix machines, nor on Windows, so you must take some care to ensure +that your locale is set properly before starting Bacula. + +To ensure that Bacula configuration files can be correctly read including +foreign characters the {bf LANG} environment variable +must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The +exact syntax may vary a bit from OS to OS, and exactly how you define +it will also vary. On most newer Win32 machines, you can use {\bf notepad} +to edit the conf files, then choose output encoding UTF-8. + +Bacula assumes that all filenames are in UTF-8 format on Linux and +Unix machines. On Win32 they are in Unicode (UTF-16), and will +be automatically converted to UTF-8 format. + +\section{Resource Directive Format} +\index[general]{Resource Directive Format } +\index[general]{Format!Resource Directive } + +Although, you won't need to know the details of all the directives a basic +knowledge of Bacula resource directives is essential. Each directive contained +within the resource (within the braces) is composed of a keyword followed by +an equal sign (=) followed by one or more values. The keywords must be one of +the known Bacula resource record keywords, and it may be composed of upper or +lower case characters and spaces. + +Each resource definition MUST contain a Name directive, and may optionally +contain a Description directive. The Name directive is used to +uniquely identify the resource. The Description directive is (will be) used +during display of the Resource to provide easier human recognition. For +example: + +\footnotesize +\begin{verbatim} +Director { + Name = "MyDir" + Description = "Main Bacula Director" + WorkingDirectory = "$HOME/bacula/bin/working" +} +\end{verbatim} +\normalsize + +Defines the Director resource with the name "MyDir" and a working directory +\$HOME/bacula/bin/working. In general, if you want spaces in a name to the +right of the first equal sign (=), you must enclose that name within double +quotes. Otherwise quotes are not generally necessary because once defined, +quoted strings and unquoted strings are all equal. + +\label{Comments} +\subsection{Comments} +\index[general]{Comments} + +When reading the configuration file, blank lines are ignored and everything +after a hash sign (\#) until the end of the line is taken to be a comment. A +semicolon (;) is a logical end of line, and anything after the semicolon is +considered as the next statement. If a statement appears on a line by itself, +a semicolon is not necessary to terminate it, so generally in the examples in +this manual, you will not see many semicolons. +\label{Case1} + +\subsection{Upper and Lower Case and Spaces} +\index[general]{Spaces!Upper/Lower Case} +\index[general]{Upper and Lower Case and Spaces} + +Case (upper/lower) and spaces are totally ignored in the resource directive +keywords (the part before the equal sign). + +Within the keyword (i.e. before the equal sign), spaces are not significant. +Thus the keywords: {\bf name}, {\bf Name}, and {\bf N a m e} are all +identical. + +Spaces after the equal sign and before the first character of the value are +ignored. + +In general, spaces within a value are significant (not ignored), and if the +value is a name, you must enclose the name in double quotes for the spaces to +be accepted. Names may contain up to 127 characters. Currently, a name may +contain any ASCII character. Within a quoted string, any character following a +backslash (\textbackslash{}) is taken as itself (handy for inserting +backslashes and double quotes (")). + +Please note, however, that Bacula resource names as well as certain other +names (e.g. Volume names) must contain only letters (including ISO accented +letters), numbers, and a few special characters (space, underscore, ...). +All other characters and punctuation are invalid. + +\label{Includes} +\subsection{Including other Configuration Files} +\index[general]{Including other Configuration Files } +\index[general]{Files!Including other Configuration } +\index[general]{Using @ to include other files} +\index[general]{@{\bf filename}} + +If you wish to break your configuration file into smaller pieces, you can do +so by including other files using the syntax @{\bf filename} where {\bf +filename} is the full path and filename of another file. The @filename +specification can be given anywhere a primitive token would appear. + +\label{DataTypes} +\subsection{Recognized Primitive Data Types} +\index[general]{Types!Recognized Primitive Data } +\index[general]{Recognized Primitive Data Types } + +When parsing the resource directives, Bacula classifies the data according to +the types listed below. The first time you read this, it may appear a bit +overwhelming, but in reality, it is all pretty logical and straightforward. + +\begin{description} + +\item [name] + \index[fd]{name} + A keyword or name consisting of alphanumeric characters, including the +hyphen, underscore, and dollar characters. The first character of a {\bf +name} must be a letter. A name has a maximum length currently set to 127 +bytes. Typically keywords appear on the left side of an equal (i.e. they are +Bacula keywords -- i.e. Resource names or directive names). Keywords may not +be quoted. + +\item [name-string] + \index[fd]{name-string} + A name-string is similar to a name, except that the name may be quoted and +can thus contain additional characters including spaces. Name strings are +limited to 127 characters in length. Name strings are typically used on the +right side of an equal (i.e. they are values to be associated with a keyword). + + +\item [string] + \index[fd]{string} + A quoted string containing virtually any character including spaces, or a +non-quoted string. A string may be of any length. Strings are typically +values that correspond to filenames, directories, or system command names. A +backslash (\textbackslash{}) turns the next character into itself, so to +include a double quote in a string, you precede the double quote with a +backslash. Likewise to include a backslash. + +\item [directory] + \index[dir]{directory} + A directory is either a quoted or non-quoted string. A directory will be +passed to your standard shell for expansion when it is scanned. Thus +constructs such as {\bf \$HOME} are interpreted to be their correct values. + +\item [password] + \index[dir]{password} + This is a Bacula password and it is stored internally in MD5 hashed format. + +\item [integer] + \index[dir]{integer} + A 32 bit integer value. It may be positive or negative. + +\item [positive integer] + \index[dir]{positive integer } + A 32 bit positive integer value. + +\item [long integer] + \index[dir]{long integer} + A 64 bit integer value. Typically these are values such as bytes that can +exceed 4 billion and thus require a 64 bit value. + +\item [yes|no] + \index[dir]{yes or no } + Either a {\bf yes} or a {\bf no}. + +\label{Size1} +\item [size] +\index[dir]{size} +A size specified as bytes. Typically, this is a floating point scientific +input format followed by an optional modifier. The floating point input is +stored as a 64 bit integer value. If a modifier is present, it must +immediately follow the value with no intervening spaces. The following +modifiers are permitted: + +\begin{description} +\item [k] + 1,024 (kilobytes) + +\item [kb] + 1,000 (kilobytes) + +\item [m] + 1,048,576 (megabytes) + +\item [mb] + 1,000,000 (megabytes) + +\item [g] + 1,073,741,824 (gigabytes) + +\item [gb] + 1,000,000,000 (gigabytes) +\end{description} + +\label{Time} +\item [time] +\index[dir]{time} +A time or duration specified in seconds. The time is stored internally as +a 64 bit integer value, but it is specified in two parts: a number part and +a modifier part. The number can be an integer or a floating point number. +If it is entered in floating point notation, it will be rounded to the +nearest integer. The modifier is mandatory and follows the number part, +either with or without intervening spaces. The following modifiers are +permitted: + +\begin{description} + +\item [seconds] + \index[dir]{seconds} + seconds + +\item [minutes] + \index[dir]{minutes} + minutes (60 seconds) + +\item [hours] + \index[dir]{hours } + hours (3600 seconds) + +\item [days] + \index[dir]{days} + days (3600*24 seconds) + +\item [weeks] + \index[dir]{weeks} + weeks (3600*24*7 seconds) + +\item [months] + \index[dir]{months } + months (3600*24*30 seconds) + +\item [quarters] + \index[dir]{quarters } + quarters (3600*24*91 seconds) + +\item [years] + \index[dir]{years } + years (3600*24*365 seconds) +\end{description} + +Any abbreviation of these modifiers is also permitted (i.e. {\bf seconds} +may be specified as {\bf sec} or {\bf s}). A specification of {\bf m} will +be taken as months. + +The specification of a time may have as many number/modifier parts as you +wish. For example: + +\footnotesize +\begin{verbatim} +1 week 2 days 3 hours 10 mins +1 month 2 days 30 sec + +\end{verbatim} +\normalsize + +are valid date specifications. + +\end{description} + +\label{ResTypes} +\section{Resource Types} +\index[general]{Types!Resource } +\index[general]{Resource Types } + +The following table lists all current Bacula resource types. It shows what +resources must be defined for each service (daemon). The default configuration +files will already contain at least one example of each permitted resource, so +you need not worry about creating all these kinds of resources from scratch. + +\addcontentsline{lot}{table}{Resource Types} +\begin{longtable}{|l|l|l|l|l|} + \hline +\multicolumn{1}{|c| }{\bf Resource } & \multicolumn{1}{c| }{\bf Director } & +\multicolumn{1}{c| }{\bf Client } & \multicolumn{1}{c| }{\bf Storage } & +\multicolumn{1}{c| }{\bf Console } \\ + \hline +{Autochanger } & {No } & {No } & {Yes } & {No } \\ +\hline +{Catalog } & {Yes } & {No } & {No } & {No } \\ + \hline +{Client } & {Yes } & {Yes } & {No } & {No } \\ + \hline +{Console } & {Yes } & {No } & {No } & {Yes } \\ + \hline +{Device } & {No } & {No } & {Yes } & {No } \\ + \hline +{Director } & {Yes } & {Yes } & {Yes } & {Yes } \\ + \hline +{FileSet } & {Yes } & {No } & {No } & {No } \\ + \hline +{Job } & {Yes } & {No } & {No } & {No } \\ + \hline +{JobDefs } & {Yes } & {No } & {No } & {No } \\ + \hline +{Message } & {Yes } & {Yes } & {Yes } & {No } \\ + \hline +{Pool } & {Yes } & {No } & {No } & {No } \\ + \hline +{Schedule } & {Yes } & {No } & {No } & {No } \\ + \hline +{Storage } & {Yes } & {No } & {Yes } & {No } +\\ \hline + +\end{longtable} + +\section{Names, Passwords and Authorization} +\label{Names} +\index[general]{Authorization!Names Passwords and } +\index[general]{Names, Passwords and Authorization } +\index[general]{Passwords} + +In order for one daemon to contact another daemon, it must authorize itself +with a password. In most cases, the password corresponds to a particular name, +so both the name and the password must match to be authorized. Passwords are +plain text, any text. They are not generated by any special process; just +use random text. + +The default configuration files are automatically defined for correct +authorization with random passwords. If you add to or modify these files, you +will need to take care to keep them consistent. + +Here is sort of a picture of what names/passwords in which files/Resources +must match up: + +\includegraphics{./Conf-Diagram.eps} + +In the left column, you will find the Director, Storage, and Client resources, +with their names and passwords -- these are all in {\bf bacula-dir.conf}. In +the right column are where the corresponding values should be found in the +Console, Storage daemon (SD), and File daemon (FD) configuration files. + +Please note that the Address, {\bf fd-sd}, that appears in the Storage +resource of the Director, preceded with and asterisk in the above example, is +passed to the File daemon in symbolic form. The File daemon then resolves it +to an IP address. For this reason, you must use either an IP address or a +fully qualified name. A name such as {\bf localhost}, not being a fully +qualified name, will resolve in the File daemon to the localhost of the File +daemon, which is most likely not what is desired. The password used for the +File daemon to authorize with the Storage daemon is a temporary password +unique to each Job created by the daemons and is not specified in any .conf +file. + +\section{Detailed Information for each Daemon} +\index[general]{Detailed Information for each Daemon } +\index[general]{Daemon!Detailed Information for each } + +The details of each Resource and the directives permitted therein are +described in the following chapters. + +The following configuration files must be defined: + +\begin{itemize} +\item + \ilink{Console}{ConsoleConfChapter} -- to define the resources for + the Console program (user interface to the Director). It defines which +Directors are available so that you may interact with them. +\item + \ilink{Director}{DirectorChapter} -- to define the resources + necessary for the Director. You define all the Clients and Storage daemons +that you use in this configuration file. +\item + \ilink{Client}{FiledConfChapter} -- to define the resources for + each client to be backed up. That is, you will have a separate Client +resource file on each machine that runs a File daemon. +\item + \ilink{Storage}{StoredConfChapter} -- to define the resources to + be used by each Storage daemon. Normally, you will have a single Storage +daemon that controls your tape drive or tape drives. However, if you have +tape drives on several machines, you will have at least one Storage daemon +per machine. +\end{itemize} diff --git a/docs/manuals/fr/install/consoleconf.tex b/docs/manuals/fr/install/consoleconf.tex new file mode 100644 index 00000000..563c81ad --- /dev/null +++ b/docs/manuals/fr/install/consoleconf.tex @@ -0,0 +1,356 @@ +%% +%% + +\chapter{Console Configuration} +\label{ConsoleConfChapter} +\index[general]{Configuration!Console} +\index[general]{Console Configuration} + +\section{General} +\index[general]{General} + +The Console configuration file is the simplest of all the configuration files, +and in general, you should not need to change it except for the password. It +simply contains the information necessary to contact the Director or +Directors. + +For a general discussion of the syntax of configuration files and their +resources including the data types recognized by {\bf Bacula}, please see +the \ilink{Configuration}{ConfigureChapter} chapter of this manual. + +The following Console Resource definition must be defined: + +\section{The Director Resource} +\label{DirectorResource3} +\index[general]{Director Resource} +\index[general]{Resource!Director} + +The Director resource defines the attributes of the Director running on the +network. You may have multiple Director resource specifications in a single +Console configuration file. If you have more than one, you will be prompted to +choose one when you start the {\bf Console} program. + +\begin{description} +\item [Director] + \index[console]{Director} + Start of the Director directives. + +\item [Name = \lt{}name\gt{}] + \index[console]{Name} + The director name used to select among different Directors, otherwise, this + name is not used. + +\item [DIRPort = \lt{}port-number\gt{}] + \index[dir]{DIRPort} + Specify the port to use to connect to the Director. This value will most + likely already be set to the value you specified on the {\bf + \verb:--:with-base-port} option of the {\bf ./configure} command. This port must be + identical to the {\bf DIRport} specified in the {\bf Director} resource of + the \ilink{Director's configuration}{DirectorChapter} file. The + default is 9101 so this directive is not normally specified. + +\item [Address = \lt{}address\gt{}] + \index[dir]{Address} + Where the address is a host name, a fully qualified domain name, or a network + address used to connect to the Director. + +\item [Password = \lt{}password\gt{}] + \index[dir]{Password} + Where the password is the password needed for the Director to accept the + Console connection. This password must be identical to the {\bf Password} + specified in the {\bf Director} resource of the + \ilink{Director's configuration}{DirectorChapter} file. This + directive is required. +\end{description} + +An actual example might be: + +\footnotesize +\begin{verbatim} +Director { + Name = HeadMan + address = rufus.cats.com + password = xyz1erploit +} +\end{verbatim} +\normalsize + +\section{The ConsoleFont Resource} +\index[general]{Resource!ConsoleFont} +\index[general]{ConsoleFont Resource} + +The ConsoleFont resource is available only in the GNOME version of the +console. It permits you to define the font that you want used to display in +the main listing window. + +\begin{description} + +\item [ConsoleFont] + \index[console]{ConsoleFont} + Start of the ConsoleFont directives. + +\item [Name = \lt{}name\gt{}] + \index[console]{Name} + The name of the font. + +\item [Font = \lt{}Pango Font Name\gt{}] + \index[console]{Font} + The string value given here defines the desired font. It is specified in the + Pango format. For example, the default specification is: + +\footnotesize +\begin{verbatim} +Font = "LucidaTypewriter 9" +\end{verbatim} +\normalsize + +\end{description} + +Thanks to Phil Stracchino for providing the code for this feature. + +An different example might be: + +\footnotesize +\begin{verbatim} +ConsoleFont { + Name = Default + Font = "Monospace 10" +} +\end{verbatim} +\normalsize + +\section{The Console Resource} +\label{ConsoleResource} +\index[general]{Console Resource} +\index[general]{Resource!Console} + +As of Bacula version 1.33 and higher, there are three different kinds of +consoles, which the administrator or user can use to interact with the +Director. These three kinds of consoles comprise three different security +levels. + +\begin{itemize} +\item The first console type is an {\bf anonymous} or {\bf default} console, + which has full privileges. There is no console resource necessary for this + type since the password is specified in the Director resource. This is the + kind of console that was initially implemented in versions prior to 1.33 and + remains valid. Typically you would use it only for administrators. + +\item The second type of console, and new to version 1.33 and higher is a + "named" or "restricted" console defined within a Console resource in + both the Director's configuration file and in the Console's + configuration file. Both the names and the passwords in these two + entries must match much as is the case for Client programs. + + This second type of console begins with absolutely no privileges except + those explicitly specified in the Director's Console resource. Note, + the definition of what these restricted consoles can do is determined + by the Director's conf file. + + Thus you may define within the Director's conf file multiple Consoles + with different names and passwords, sort of like multiple users, each + with different privileges. As a default, these consoles can do + absolutely nothing -- no commands what so ever. You give them + privileges or rather access to commands and resources by specifying + access control lists in the Director's Console resource. This gives the + administrator fine grained control over what particular consoles (or + users) can do. + +\item The third type of console is similar to the above mentioned + restricted console in that it requires a Console resource definition in + both the Director and the Console. In addition, if the console name, + provided on the {\bf Name =} directive, is the same as a Client name, + the user of that console is permitted to use the {\bf SetIP} command to + change the Address directive in the Director's client resource to the IP + address of the Console. This permits portables or other machines using + DHCP (non-fixed IP addresses) to "notify" the Director of their current + IP address. + +\end{itemize} + +The Console resource is optional and need not be specified. However, if it is +specified, you can use ACLs (Access Control Lists) in the Director's +configuration file to restrict the particular console (or user) to see only +information pertaining to his jobs or client machine. + +You may specify as many Console resources in the console's conf file. If +you do so, generally the first Console resource will be used. However, if +you have multiple Director resources (i.e. you want to connect to different +directors), you can bind one of your Console resources to a particular +Director resource, and thus when you choose a particular Director, the +appropriate Console configuration resource will be used. See the "Director" +directive in the Console resource described below for more information. + +Note, the Console resource is optional, but can be useful for +restricted consoles as noted above. + +\begin{description} +\item [Console] + \index[console]{Console} + Start of the Console resource. + +\item [Name = \lt{}name\gt{}] + \index[console]{Name} + The Console name used to allow a restricted console to change + its IP address using the SetIP command. The SetIP command must + also be defined in the Director's conf CommandACL list. + + +\item [Password = \lt{}password\gt{}] + \index[console]{Password} + If this password is supplied, then the password specified in the + Director resource of you Console conf will be ignored. See below + for more details. + +\item [Director = \lt{}director-resource-name\gt{}] + If this directive is specified, this Console resource will be + used by bconsole when that particular director is selected + when first starting bconsole. I.e. it binds a particular console + resource with its name and password to a particular director. + +\item [Heartbeat Interval = \lt{}time-interval\gt{}] + \index[console]{Heartbeat Interval} + \index[console]{Directive!Heartbeat} + This directive is optional and if specified will cause the Console to + set a keepalive interval (heartbeat) in seconds on each of the sockets + to communicate with the Director. It is implemented only on systems + (Linux, ...) that provide the {\bf setsockopt} TCP\_KEEPIDLE function. + The default value is zero, which means no change is made to the socket. + +\end{description} + + +The following configuration files were supplied by Phil Stracchino. For +example, if we define the following in the user's bconsole.conf file (or +perhaps the bwx-console.conf file): + +\footnotesize +\begin{verbatim} +Director { + Name = MyDirector + DIRport = 9101 + Address = myserver + Password = "XXXXXXXXXXX" # no, really. this is not obfuscation. +} + + +Console { + Name = restricted-user + Password = "UntrustedUser" +} +\end{verbatim} +\normalsize + +Where the Password in the Director section is deliberately incorrect, and the +Console resource is given a name, in this case {\bf restricted-user}. Then +in the Director's bacula-dir.conf file (not directly accessible by the user), +we define: + +\footnotesize +\begin{verbatim} +Console { + Name = restricted-user + Password = "UntrustedUser" + JobACL = "Restricted Client Save" + ClientACL = restricted-client + StorageACL = main-storage + ScheduleACL = *all* + PoolACL = *all* + FileSetACL = "Restricted Client's FileSet" + CatalogACL = DefaultCatalog + CommandACL = run +} +\end{verbatim} +\normalsize + +the user logging into the Director from his Console will get logged in as {\bf +restricted-user}, and he will only be able to see or access a Job with the +name {\bf Restricted Client Save} a Client with the name {\bf +restricted-client}, a Storage device {\bf main-storage}, any Schedule or Pool, +a FileSet named {\bf Restricted Client's FileSet}, a Catalog named {\bf +DefaultCatalog}, and the only command he can use in the Console is the {\bf +run} command. In other words, this user is rather limited in what he can see +and do with Bacula. + +The following is an example of a bconsole conf file that can access +several Directors and has different Consoles depending on the director: + +\footnotesize +\begin{verbatim} +Director { + Name = MyDirector + DIRport = 9101 + Address = myserver + Password = "XXXXXXXXXXX" # no, really. this is not obfuscation. +} + +Director { + Name = SecondDirector + DIRport = 9101 + Address = secondserver + Password = "XXXXXXXXXXX" # no, really. this is not obfuscation. +} + +Console { + Name = restricted-user + Password = "UntrustedUser" + Director = MyDirector +} + +Console { + Name = restricted-user + Password = "A different UntrustedUser" + Director = SecondDirector +} +\end{verbatim} +\normalsize + +The second Director referenced at "secondserver" might look +like the following: + +\footnotesize +\begin{verbatim} +Console { + Name = restricted-user + Password = "A different UntrustedUser" + JobACL = "Restricted Client Save" + ClientACL = restricted-client + StorageACL = second-storage + ScheduleACL = *all* + PoolACL = *all* + FileSetACL = "Restricted Client's FileSet" + CatalogACL = RestrictedCatalog + CommandACL = run, restore + WhereACL = "/" +} +\end{verbatim} +\normalsize + + + +\section{Console Commands} +\index[general]{Console Commands} +\index[general]{Commands!Console} + +For more details on running the console and its commands, please see the +\ilink{Bacula Console}{_ConsoleChapter} chapter of this manual. + +\section{Sample Console Configuration File} +\label{SampleConfiguration2} +\index[general]{File!Sample Console Configuration} +\index[general]{Sample Console Configuration File} + +An example Console configuration file might be the following: + +\footnotesize +\begin{verbatim} +# +# Bacula Console Configuration File +# +Director { + Name = HeadMan + address = "my_machine.my_domain.com" + Password = Console_password +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/install/critical.tex b/docs/manuals/fr/install/critical.tex new file mode 100644 index 00000000..30462e39 --- /dev/null +++ b/docs/manuals/fr/install/critical.tex @@ -0,0 +1,130 @@ +%% +%% + +\chapter{Critical Items to Implement Before Production} +\label{CriticalChapter} +\index[general]{Production!Critical Items to Implement Before } +\index[general]{Critical Items to Implement Before Production } + +We recommend you take your time before implementing a production a Bacula +backup system since Bacula is a rather complex program, and if you make a +mistake, you may suddenly find that you cannot restore your files in case +of a disaster. This is especially true if you have not previously used a +major backup product. + +If you follow the instructions in this chapter, you will have covered most of +the major problems that can occur. It goes without saying that if you ever +find that we have left out an important point, please inform us, so +that we can document it to the benefit of everyone. + +\label{Critical} +\section{Critical Items} +\index[general]{Critical Items } +\index[general]{Items!Critical } + +The following assumes that you have installed Bacula, you more or less +understand it, you have at least worked through the tutorial or have +equivalent experience, and that you have set up a basic production +configuration. If you haven't done the above, please do so and then come back +here. The following is a sort of checklist that points with perhaps a brief +explanation of why you should do it. In most cases, you will find the +details elsewhere in the manual. The order is more or less the order you +would use in setting up a production system (if you already are in +production, use the checklist anyway). + +\begin{itemize} +\item Test your tape drive for compatibility with Bacula by using the test + command in the \ilink{btape}{btape} program. +\item Better than doing the above is to walk through the nine steps in the + \ilink{Tape Testing}{TapeTestingChapter} chapter of the manual. It + may take you a bit of time, but it will eliminate surprises. +\item Test the end of tape handling of your tape drive by using the + fill command in the \ilink{btape}{btape} program. +\item If you are using a Linux 2.4 kernel, make sure that /lib/tls is disabled. Bacula + does not work with this library. See the second point under + \ilink{ Supported Operating Systems.}{SupportedOSes} +\item Do at least one restore of files. If you backup multiple OS types + (Linux, Solaris, HP, MacOS, FreeBSD, Win32, ...), + restore files from each system type. The + \ilink{Restoring Files}{RestoreChapter} chapter shows you how. +\item Write a bootstrap file to a separate system for each backup job. The + Write Bootstrap directive is described in the + \ilink{Director Configuration}{writebootstrap} chapter of the + manual, and more details are available in the + \ilink{Bootstrap File}{BootstrapChapter} chapter. Also, the default + bacula-dir.conf comes with a Write Bootstrap directive defined. This allows + you to recover the state of your system as of the last backup. +\item Backup your catalog. An example of this is found in the default + bacula-dir.conf file. The backup script is installed by default and + should handle any database, though you may want to make your own local + modifications. See also \ilink{Backing Up Your Bacula Database - + Security Considerations }{BackingUpBaculaSecurityConsiderations} for more + information. +\item Write a bootstrap file for the catalog. An example of this is found in + the default bacula-dir.conf file. This will allow you to quickly restore your + catalog in the event it is wiped out -- otherwise it is many excruciating + hours of work. +\item Make a copy of the bacula-dir.conf, bacula-sd.conf, and + bacula-fd.conf files that you are using on your server. Put it in a safe + place (on another machine) as these files can be difficult to + reconstruct if your server dies. +\item Make a Bacula Rescue CDROM! See the + \ilink{Disaster Recovery Using a Bacula Rescue + CDROM}{RescueChapter} chapter. It is trivial to make such a CDROM, + and it can make system recovery in the event of a lost hard disk infinitely + easier. +\item Bacula assumes all filenames are in UTF-8 format. This is important + when saving the filenames to the catalog. For Win32 machine, Bacula will + automatically convert from Unicode to UTF-8, but on Unix, Linux, *BSD, + and MacOS X machines, you must explicitly ensure that your locale is set + properly. Typically this means that the {bf LANG} environment variable + must end in {\bf .UTF-8}. An full example is {\bf en\_US.UTF-8}. The + exact syntax may vary a bit from OS to OS, and exactly how you define it + will also vary. + + On most modern Win32 machines, you can edit the conf files with {\bf + notebook} and choose output encoding UTF-8. +\end{itemize} + +\section{Recommended Items} +\index[general]{Items!Recommended } +\index[general]{Recommended Items } + +Although these items may not be critical, they are recommended and will help +you avoid problems. + +\begin{itemize} +\item Read the \ilink{Quick Start Guide to Bacula}{QuickStartChapter} +\item After installing and experimenting with Bacula, read and work carefully + through the examples in the + \ilink{Tutorial}{TutorialChapter} chapter of this manual. +\item Learn what each of the \ilink{Bacula Utility Programs}{_UtilityChapter} + does. +\item Set up reasonable retention periods so that your catalog does not grow + to be too big. See the following three chapters:\\ + \ilink{Recycling your Volumes}{RecyclingChapter},\\ + \ilink{Basic Volume Management}{DiskChapter},\\ + \ilink{Using Pools to Manage Volumes}{PoolsChapter}. +\item Perform a bare metal recovery using the Bacula Rescue CDROM. See the + \ilink{Disaster Recovery Using a Bacula Rescue CDROM}{RescueChapter} + chapter. +\end{itemize} + +If you absolutely must implement a system where you write a different +tape each night and take it offsite in the morning. We recommend that you do +several things: +\begin{itemize} +\item Write a bootstrap file of your backed up data and a bootstrap file + of your catalog backup to a floppy disk or a CDROM, and take that with + the tape. If this is not possible, try to write those files to another + computer or offsite computer, or send them as email to a friend. If none + of that is possible, at least print the bootstrap files and take that + offsite with the tape. Having the bootstrap files will make recovery + much easier. +\item It is better not to force Bacula to load a particular tape each day. + Instead, let Bacula choose the tape. If you need to know what tape to + mount, you can print a list of recycled and appendable tapes daily, and + select any tape from that list. Bacula may propose a particular tape + for use that it considers optimal, but it will accept any valid tape + from the correct pool. +\end{itemize} diff --git a/docs/manuals/fr/install/dirdconf.tex b/docs/manuals/fr/install/dirdconf.tex new file mode 100644 index 00000000..c823d640 --- /dev/null +++ b/docs/manuals/fr/install/dirdconf.tex @@ -0,0 +1,3377 @@ +%% +%% + +\chapter{Configuring the Director} +\label{DirectorChapter} +\index[general]{Director!Configuring the} +\index[general]{Configuring the Director} + +Of all the configuration files needed to run {\bf Bacula}, the Director's is +the most complicated, and the one that you will need to modify the most often +as you add clients or modify the FileSets. + +For a general discussion of configuration files and resources including the +data types recognized by {\bf Bacula}. Please see the +\ilink{Configuration}{ConfigureChapter} chapter of this manual. + +\section{Director Resource Types} +\index[general]{Types!Director Resource} +\index[general]{Director Resource Types} + +Director resource type may be one of the following: + +Job, JobDefs, Client, Storage, Catalog, Schedule, FileSet, Pool, Director, or +Messages. We present them here in the most logical order for defining them: + +Note, everything revolves around a job and is tied to a job in one +way or another. + +\begin{itemize} +\item + \ilink{Director}{DirectorResource4} -- to define the Director's + name and its access password used for authenticating the Console program. + Only a single Director resource definition may appear in the Director's + configuration file. If you have either {\bf /dev/random} or {\bf bc} on your + machine, Bacula will generate a random password during the configuration + process, otherwise it will be left blank. +\item + \ilink{Job}{JobResource} -- to define the backup/restore Jobs + and to tie together the Client, FileSet and Schedule resources to be used + for each Job. Normally, you will Jobs of different names corresponding + to each client (i.e. one Job per client, but a different one with a different name + for each client). +\item + \ilink{JobDefs}{JobDefsResource} -- optional resource for + providing defaults for Job resources. +\item + \ilink{Schedule}{ScheduleResource} -- to define when a Job is to + be automatically run by {\bf Bacula's} internal scheduler. You + may have any number of Schedules, but each job will reference only + one. +\item + \ilink{FileSet}{FileSetResource} -- to define the set of files + to be backed up for each Client. You may have any number of + FileSets but each Job will reference only one. +\item + \ilink{Client}{ClientResource2} -- to define what Client is to be + backed up. You will generally have multiple Client definitions. Each + Job will reference only a single client. +\item + \ilink{Storage}{StorageResource2} -- to define on what physical + device the Volumes should be mounted. You may have one or + more Storage definitions. +\item + \ilink{Pool}{PoolResource} -- to define the pool of Volumes + that can be used for a particular Job. Most people use a + single default Pool. However, if you have a large number + of clients or volumes, you may want to have multiple Pools. + Pools allow you to restrict a Job (or a Client) to use + only a particular set of Volumes. +\item + \ilink{Catalog}{CatalogResource} -- to define in what database to + keep the list of files and the Volume names where they are backed up. + Most people only use a single catalog. However, if you want to + scale the Director to many clients, multiple catalogs can be helpful. + Multiple catalogs require a bit more management because in general + you must know what catalog contains what data. Currently, all + Pools are defined in each catalog. This restriction will be removed + in a later release. +\item + \ilink{Messages}{MessagesChapter} -- to define where error and + information messages are to be sent or logged. You may define + multiple different message resources and hence direct particular + classes of messages to different users or locations (files, ...). +\end{itemize} + +\section{The Director Resource} +\label{DirectorResource4} +\index[general]{Director Resource} +\index[general]{Resource!Director} + +The Director resource defines the attributes of the Directors running on the +network. In the current implementation, there is only a single Director +resource, but the final design will contain multiple Directors to maintain +index and media database redundancy. + +\begin{description} + +\item [Director] + \index[dir]{Director} + Start of the Director resource. One and only one director resource must be +supplied. + +\item [Name = \lt{}name\gt{}] + \index[dir]{Name} + \index[dir]{Directive!Name} + The director name used by the system administrator. This directive is +required. + +\item [Description = \lt{}text\gt{}] + \index[dir]{Description} + \index[dir]{Directive!Description} + The text field contains a description of the Director that will be displayed +in the graphical user interface. This directive is optional. + +\item [Password = \lt{}UA-password\gt{}] + \index[dir]{Password} + \index[dir]{Directive!Password} + Specifies the password that must be supplied for the default Bacula + Console to be authorized. The same password must appear in the {\bf + Director} resource of the Console configuration file. For added + security, the password is never passed across the network but instead a + challenge response hash code created with the password. This directive + is required. If you have either {\bf /dev/random} or {\bf bc} on your + machine, Bacula will generate a random password during the configuration + process, otherwise it will be left blank and you must manually supply + it. + + The password is plain text. It is not generated through any special + process but as noted above, it is better to use random text for + security reasons. + +\item [Messages = \lt{}Messages-resource-name\gt{}] + \index[dir]{Messages} + \index[dir]{Directive!Messages} + The messages resource specifies where to deliver Director messages that are + not associated with a specific Job. Most messages are specific to a job and + will be directed to the Messages resource specified by the job. However, + there are a few messages that can occur when no job is running. This + directive is required. + +\item [Working Directory = \lt{}Directory\gt{}] + \index[dir]{Working Directory} + \index[dir]{Directive!Working Directory} + This directive is mandatory and specifies a directory in which the Director + may put its status files. This directory should be used only by Bacula but + may be shared by other Bacula daemons. However, please note, if this + directory is shared with other Bacula daemons (the File daemon and Storage + daemon), you must ensure that the {\bf Name} given to each daemon is + unique so that the temporary filenames used do not collide. By default + the Bacula configure process creates unique daemon names by postfixing them + with -dir, -fd, and -sd. Standard shell expansion of the {\bf + Directory} is done when the configuration file is read so that values such + as {\bf \$HOME} will be properly expanded. This directive is required. + The working directory specified must already exist and be + readable and writable by the Bacula daemon referencing it. + + If you have specified a Director user and/or a Director group on your + ./configure line with {\bf {-}{-}with-dir-user} and/or + {\bf {-}{-}with-dir-group} the Working Directory owner and group will + be set to those values. + +\item [Pid Directory = \lt{}Directory\gt{}] + \index[dir]{Pid Directory} + \index[dir]{Directive!Pid Directory} + This directive is mandatory and specifies a directory in which the Director + may put its process Id file. The process Id file is used to shutdown + Bacula and to prevent multiple copies of Bacula from running simultaneously. + Standard shell expansion of the {\bf Directory} is done when the + configuration file is read so that values such as {\bf \$HOME} will be + properly expanded. + + The PID directory specified must already exist and be + readable and writable by the Bacula daemon referencing it + + Typically on Linux systems, you will set this to: {\bf /var/run}. If you are + not installing Bacula in the system directories, you can use the {\bf Working + Directory} as defined above. This directive is required. + +\item [Scripts Directory = \lt{}Directory\gt{}] + \index[dir]{Scripts Directory} + \index[dir]{Directive!Scripts Directory} + This directive is optional and, if defined, specifies a directory in + which the Director will look for the Python startup script {\bf + DirStartup.py}. This directory may be shared by other Bacula daemons. + Standard shell expansion of the directory is done when the configuration + file is read so that values such as {\bf \$HOME} will be properly + expanded. + +\item [QueryFile = \lt{}Path\gt{}] + \index[dir]{QueryFile} + \index[dir]{Directive!QueryFile} + This directive is mandatory and specifies a directory and file in which + the Director can find the canned SQL statements for the {\bf Query} + command of the Console. Standard shell expansion of the {\bf Path} is + done when the configuration file is read so that values such as {\bf + \$HOME} will be properly expanded. This directive is required. + +\label{DirMaxConJobs} +\item [Maximum Concurrent Jobs = \lt{}number\gt{}] +\index[dir]{Maximum Concurrent Jobs} +\index[dir]{Directive!Maximum Concurrent Jobs} +\index[general]{Simultaneous Jobs} +\index[general]{Concurrent Jobs} + where \lt{}number\gt{} is the maximum number of total Director Jobs that + should run concurrently. The default is set to 1, but you may set it to a + larger number. + + Please note that the Volume format becomes much more complicated with + multiple simultaneous jobs, consequently, restores can take much longer if + Bacula must sort through interleaved volume blocks from multiple simultaneous + jobs. This can be avoided by having each simultaneously running job write to + a different volume or by using data spooling, which will first spool the data + to disk simultaneously, then write each spool file to the volume in + sequence. + + There may also still be some cases where directives such as {\bf Maximum + Volume Jobs} are not properly synchronized with multiple simultaneous jobs + (subtle timing issues can arise), so careful testing is recommended. + + At the current time, there is no configuration parameter set to limit the + number of console connections. A maximum of five simultaneous console + connections are permitted. + +\item [FD Connect Timeout = \lt{}time\gt{}] + \index[dir]{FD Connect Timeout} + \index[dir]{Directive!FD Connect Timeout} + where {\bf time} is the time that the Director should continue + attempting to contact the File daemon to start a job, and after which + the Director will cancel the job. The default is 30 minutes. + +\item [SD Connect Timeout = \lt{}time\gt{}] + \index[dir]{SD Connect Timeout} + \index[dir]{Directive!SD Connect Timeout} + where {\bf time} is the time that the Director should continue + attempting to contact the Storage daemon to start a job, and after which + the Director will cancel the job. The default is 30 minutes. + +\item [DirAddresses = \lt{}IP-address-specification\gt{}] + \index[dir]{DirAddresses} + \index[dir]{Address} + \index[general]{Address} + \index[dir]{Directive!DirAddresses} + Specify the ports and addresses on which the Director daemon will listen + for Bacula Console connections. Probably the simplest way to explain + this is to show an example: + +\footnotesize +\begin{verbatim} + DirAddresses = { + ip = { addr = 1.2.3.4; port = 1205;} + ipv4 = { + addr = 1.2.3.4; port = http;} + ipv6 = { + addr = 1.2.3.4; + port = 1205; + } + ip = { + addr = 1.2.3.4 + port = 1205 + } + ip = { addr = 1.2.3.4 } + ip = { addr = 201:220:222::2 } + ip = { + addr = bluedot.thun.net + } +} +\end{verbatim} +\normalsize + +where ip, ip4, ip6, addr, and port are all keywords. Note, that the address +can be specified as either a dotted quadruple, or IPv6 colon notation, or as +a symbolic name (only in the ip specification). Also, port can be specified +as a number or as the mnemonic value from the /etc/services file. If a port +is not specified, the default will be used. If an ip section is specified, +the resolution can be made either by IPv4 or IPv6. If ip4 is specified, then +only IPv4 resolutions will be permitted, and likewise with ip6. + +Please note that if you use the DirAddresses directive, you must +not use either a DirPort or a DirAddress directive in the same +resource. + +\item [DirPort = \lt{}port-number\gt{}] + \index[dir]{DirPort} + \index[dir]{Directive!DirPort} + Specify the port (a positive integer) on which the Director daemon will + listen for Bacula Console connections. This same port number must be + specified in the Director resource of the Console configuration file. The + default is 9101, so normally this directive need not be specified. This + directive should not be used if you specify DirAddresses (not plural) + directive. + +\item [DirAddress = \lt{}IP-Address\gt{}] + \index[dir]{DirAddress} + \index[dir]{Directive!DirAddress} + This directive is optional, but if it is specified, it will cause the + Director server (for the Console program) to bind to the specified {\bf + IP-Address}, which is either a domain name or an IP address specified as a + dotted quadruple in string or quoted string format. If this directive is not + specified, the Director will bind to any available address (the default). + Note, unlike the DirAddresses specification noted above, this directive only + permits a single address to be specified. This directive should not be used if you + specify a DirAddresses (note plural) directive. + + + +\end{description} + +The following is an example of a valid Director resource definition: + +\footnotesize +\begin{verbatim} +Director { + Name = HeadMan + WorkingDirectory = "$HOME/bacula/bin/working" + Password = UA_password + PidDirectory = "$HOME/bacula/bin/working" + QueryFile = "$HOME/bacula/bin/query.sql" + Messages = Standard +} +\end{verbatim} +\normalsize + +\section{The Job Resource} +\label{JobResource} +\index[general]{Resource!Job} +\index[general]{Job Resource} + +The Job resource defines a Job (Backup, Restore, ...) that Bacula must +perform. Each Job resource definition contains the name of a Client and +a FileSet to backup, the Schedule for the Job, where the data +are to be stored, and what media Pool can be used. In effect, each Job +resource must specify What, Where, How, and When or FileSet, Storage, +Backup/Restore/Level, and Schedule respectively. Note, the FileSet must +be specified for a restore job for historical reasons, but it is no longer used. + +Only a single type ({\bf Backup}, {\bf Restore}, ...) can be specified for any +job. If you want to backup multiple FileSets on the same Client or multiple +Clients, you must define a Job for each one. + +Note, you define only a single Job to do the Full, Differential, and +Incremental backups since the different backup levels are tied together by +a unique Job name. Normally, you will have only one Job per Client, but +if a client has a really huge number of files (more than several million), +you might want to split it into to Jobs each with a different FileSet +covering only part of the total files. + + +\begin{description} + +\item [Job] + \index[dir]{Job} + \index[dir]{Directive!Job} + Start of the Job resource. At least one Job resource is required. + +\item [Name = \lt{}name\gt{}] + \index[dir]{Name} + \index[dir]{Directive!Name} + The Job name. This name can be specified on the {\bf Run} command in the + console program to start a job. If the name contains spaces, it must be + specified between quotes. It is generally a good idea to give your job the + same name as the Client that it will backup. This permits easy + identification of jobs. + + When the job actually runs, the unique Job Name will consist of the name you + specify here followed by the date and time the job was scheduled for + execution. This directive is required. + +\item [Enabled = \lt{}yes|no\gt{}] + \index[dir]{Enable} + \index[dir]{Directive!Enable} + This directive allows you to enable or disable automatic execution + via the scheduler of a Job. + +\item [Type = \lt{}job-type\gt{}] + \index[dir]{Type} + \index[dir]{Directive!Type} + The {\bf Type} directive specifies the Job type, which may be one of the + following: {\bf Backup}, {\bf Restore}, {\bf Verify}, or {\bf Admin}. This + directive is required. Within a particular Job Type, there are also Levels + as discussed in the next item. + +\begin{description} + +\item [Backup] + \index[dir]{Backup} + Run a backup Job. Normally you will have at least one Backup job for each + client you want to save. Normally, unless you turn off cataloging, most all + the important statistics and data concerning files backed up will be placed + in the catalog. + +\item [Restore] + \index[dir]{Restore} + Run a restore Job. Normally, you will specify only one Restore job + which acts as a sort of prototype that you will modify using the console + program in order to perform restores. Although certain basic + information from a Restore job is saved in the catalog, it is very + minimal compared to the information stored for a Backup job -- for + example, no File database entries are generated since no Files are + saved. + + {\bf Restore} jobs cannot be + automatically started by the scheduler as is the case for Backup, Verify + and Admin jobs. To restore files, you must use the {\bf restore} command + in the console. + + +\item [Verify] + \index[dir]{Verify} + Run a verify Job. In general, {\bf verify} jobs permit you to compare the + contents of the catalog to the file system, or to what was backed up. In + addition, to verifying that a tape that was written can be read, you can + also use {\bf verify} as a sort of tripwire intrusion detection. + +\item [Admin] + \index[dir]{Admin} + Run an admin Job. An {\bf Admin} job can be used to periodically run catalog + pruning, if you do not want to do it at the end of each {\bf Backup} Job. + Although an Admin job is recorded in the catalog, very little data is saved. +\end{description} + +\label{Level} + +\item [Level = \lt{}job-level\gt{}] +\index[dir]{Level} +\index[dir]{Directive!Level} + The Level directive specifies the default Job level to be run. Each + different Job Type (Backup, Restore, ...) has a different set of Levels + that can be specified. The Level is normally overridden by a different + value that is specified in the {\bf Schedule} resource. This directive + is not required, but must be specified either by a {\bf Level} directive + or as an override specified in the {\bf Schedule} resource. + +For a {\bf Backup} Job, the Level may be one of the following: + +\begin{description} + +\item [Full] +\index[dir]{Full} + When the Level is set to Full all files in the FileSet whether or not + they have changed will be backed up. + +\item [Incremental] + \index[dir]{Incremental} + When the Level is set to Incremental all files specified in the FileSet + that have changed since the last successful backup of the the same Job + using the same FileSet and Client, will be backed up. If the Director + cannot find a previous valid Full backup then the job will be upgraded + into a Full backup. When the Director looks for a valid backup record + in the catalog database, it looks for a previous Job with: + +\begin{itemize} +\item The same Job name. +\item The same Client name. +\item The same FileSet (any change to the definition of the FileSet such as + adding or deleting a file in the Include or Exclude sections constitutes a + different FileSet. +\item The Job was a Full, Differential, or Incremental backup. +\item The Job terminated normally (i.e. did not fail or was not canceled). +\end{itemize} + + If all the above conditions do not hold, the Director will upgrade the + Incremental to a Full save. Otherwise, the Incremental backup will be + performed as requested. + + The File daemon (Client) decides which files to backup for an + Incremental backup by comparing start time of the prior Job (Full, + Differential, or Incremental) against the time each file was last + "modified" (st\_mtime) and the time its attributes were last + "changed"(st\_ctime). If the file was modified or its attributes + changed on or after this start time, it will then be backed up. + + Some virus scanning software may change st\_ctime while + doing the scan. For example, if the virus scanning program attempts to + reset the access time (st\_atime), which Bacula does not use, it will + cause st\_ctime to change and hence Bacula will backup the file during + an Incremental or Differential backup. In the case of Sophos virus + scanning, you can prevent it from resetting the access time (st\_atime) + and hence changing st\_ctime by using the {\bf \verb:--:no-reset-atime} + option. For other software, please see their manual. + + When Bacula does an Incremental backup, all modified files that are + still on the system are backed up. However, any file that has been + deleted since the last Full backup remains in the Bacula catalog, which + means that if between a Full save and the time you do a restore, some + files are deleted, those deleted files will also be restored. The + deleted files will no longer appear in the catalog after doing another + Full save. However, to remove deleted files from the catalog during an + Incremental backup is quite a time consuming process and not currently + implemented in Bacula. + + In addition, if you move a directory rather than copy it, the files in + it do not have their modification time (st\_mtime) or their attribute + change time (st\_ctime) changed. As a consequence, those files will + probably not be backed up by an Incremental or Differential backup which + depend solely on these time stamps. If you move a directory, and wish + it to be properly backed up, it is generally preferable to copy it, then + delete the original. + +\item [Differential] + \index[dir]{Differential} + When the Level is set to Differential + all files specified in the FileSet that have changed since the last + successful Full backup of the same Job will be backed up. + If the Director cannot find a + valid previous Full backup for the same Job, FileSet, and Client, + backup, then the Differential job will be upgraded into a Full backup. + When the Director looks for a valid Full backup record in the catalog + database, it looks for a previous Job with: + +\begin{itemize} +\item The same Job name. +\item The same Client name. +\item The same FileSet (any change to the definition of the FileSet such as + adding or deleting a file in the Include or Exclude sections constitutes a + different FileSet. +\item The Job was a FULL backup. +\item The Job terminated normally (i.e. did not fail or was not canceled). +\end{itemize} + + If all the above conditions do not hold, the Director will upgrade the + Differential to a Full save. Otherwise, the Differential backup will be + performed as requested. + + The File daemon (Client) decides which files to backup for a + differential backup by comparing the start time of the prior Full backup + Job against the time each file was last "modified" (st\_mtime) and the + time its attributes were last "changed" (st\_ctime). If the file was + modified or its attributes were changed on or after this start time, it + will then be backed up. The start time used is displayed after the {\bf + Since} on the Job report. In rare cases, using the start time of the + prior backup may cause some files to be backed up twice, but it ensures + that no change is missed. As with the Incremental option, you should + ensure that the clocks on your server and client are synchronized or as + close as possible to avoid the possibility of a file being skipped. + Note, on versions 1.33 or greater Bacula automatically makes the + necessary adjustments to the time between the server and the client so + that the times Bacula uses are synchronized. + + When Bacula does a Differential backup, all modified files that are + still on the system are backed up. However, any file that has been + deleted since the last Full backup remains in the Bacula catalog, which + means that if between a Full save and the time you do a restore, some + files are deleted, those deleted files will also be restored. The + deleted files will no longer appear in the catalog after doing another + Full save. However, to remove deleted files from the catalog during a + Differential backup is quite a time consuming process and not currently + implemented in Bacula. It is, however, a planned future feature. + + As noted above, if you move a directory rather than copy it, the + files in it do not have their modification time (st\_mtime) or + their attribute change time (st\_ctime) changed. As a + consequence, those files will probably not be backed up by an + Incremental or Differential backup which depend solely on these + time stamps. If you move a directory, and wish it to be + properly backed up, it is generally preferable to copy it, then + delete the original. Alternatively, you can move the directory, then + use the {\bf touch} program to update the timestamps. + + Every once and a while, someone asks why we need Differential + backups as long as Incremental backups pickup all changed files. + There are possibly many answers to this question, but the one + that is the most important for me is that a Differential backup + effectively merges + all the Incremental and Differential backups since the last Full backup + into a single Differential backup. This has two effects: 1. It gives + some redundancy since the old backups could be used if the merged backup + cannot be read. 2. More importantly, it reduces the number of Volumes + that are needed to do a restore effectively eliminating the need to read + all the volumes on which the preceding Incremental and Differential + backups since the last Full are done. + +\end{description} + +For a {\bf Restore} Job, no level needs to be specified. + +For a {\bf Verify} Job, the Level may be one of the following: + +\begin{description} + +\item [InitCatalog] +\index[dir]{InitCatalog} + does a scan of the specified {\bf FileSet} and stores the file + attributes in the Catalog database. Since no file data is saved, you + might ask why you would want to do this. It turns out to be a very + simple and easy way to have a {\bf Tripwire} like feature using {\bf + Bacula}. In other words, it allows you to save the state of a set of + files defined by the {\bf FileSet} and later check to see if those files + have been modified or deleted and if any new files have been added. + This can be used to detect system intrusion. Typically you would + specify a {\bf FileSet} that contains the set of system files that + should not change (e.g. /sbin, /boot, /lib, /bin, ...). Normally, you + run the {\bf InitCatalog} level verify one time when your system is + first setup, and then once again after each modification (upgrade) to + your system. Thereafter, when your want to check the state of your + system files, you use a {\bf Verify} {\bf level = Catalog}. This + compares the results of your {\bf InitCatalog} with the current state of + the files. + +\item [Catalog] +\index[dir]{Catalog} + Compares the current state of the files against the state previously + saved during an {\bf InitCatalog}. Any discrepancies are reported. The + items reported are determined by the {\bf verify} options specified on + the {\bf Include} directive in the specified {\bf FileSet} (see the {\bf + FileSet} resource below for more details). Typically this command will + be run once a day (or night) to check for any changes to your system + files. + + Please note! If you run two Verify Catalog jobs on the same client at + the same time, the results will certainly be incorrect. This is because + Verify Catalog modifies the Catalog database while running in order to + track new files. + +\item [VolumeToCatalog] +\index[dir]{VolumeToCatalog} + This level causes Bacula to read the file attribute data written to the + Volume from the last Job. The file attribute data are compared to the + values saved in the Catalog database and any differences are reported. + This is similar to the {\bf Catalog} level except that instead of + comparing the disk file attributes to the catalog database, the + attribute data written to the Volume is read and compared to the catalog + database. Although the attribute data including the signatures (MD5 or + SHA1) are compared, the actual file data is not compared (it is not in + the catalog). + + Please note! If you run two Verify VolumeToCatalog jobs on the same + client at the same time, the results will certainly be incorrect. This + is because the Verify VolumeToCatalog modifies the Catalog database + while running. + +\item [DiskToCatalog] +\index[dir]{DiskToCatalog} + This level causes Bacula to read the files as they currently are on + disk, and to compare the current file attributes with the attributes + saved in the catalog from the last backup for the job specified on the + {\bf VerifyJob} directive. This level differs from the {\bf Catalog} + level described above by the fact that it doesn't compare against a + previous Verify job but against a previous backup. When you run this + level, you must supply the verify options on your Include statements. + Those options determine what attribute fields are compared. + + This command can be very useful if you have disk problems because it + will compare the current state of your disk against the last successful + backup, which may be several jobs. + + Note, the current implementation (1.32c) does not identify files that + have been deleted. +\end{description} + +\item [Verify Job = \lt{}Job-Resource-Name\gt{}] + \index[dir]{Verify Job} + \index[dir]{Directive!Verify Job} + If you run a verify job without this directive, the last job run will be + compared with the catalog, which means that you must immediately follow + a backup by a verify command. If you specify a {\bf Verify Job} Bacula + will find the last job with that name that ran. This permits you to run + all your backups, then run Verify jobs on those that you wish to be + verified (most often a {\bf VolumeToCatalog}) so that the tape just + written is re-read. + +\item [JobDefs = \lt{}JobDefs-Resource-Name\gt{}] +\index[dir]{JobDefs} +\index[dir]{Directive!JobDefs} + If a JobDefs-Resource-Name is specified, all the values contained in the + named JobDefs resource will be used as the defaults for the current Job. + Any value that you explicitly define in the current Job resource, will + override any defaults specified in the JobDefs resource. The use of + this directive permits writing much more compact Job resources where the + bulk of the directives are defined in one or more JobDefs. This is + particularly useful if you have many similar Jobs but with minor + variations such as different Clients. A simple example of the use of + JobDefs is provided in the default bacula-dir.conf file. + +\item [Bootstrap = \lt{}bootstrap-file\gt{}] +\index[dir]{Bootstrap} +\index[dir]{Directive!Bootstrap} + The Bootstrap directive specifies a bootstrap file that, if provided, + will be used during {\bf Restore} Jobs and is ignored in other Job + types. The {\bf bootstrap} file contains the list of tapes to be used + in a restore Job as well as which files are to be restored. + Specification of this directive is optional, and if specified, it is + used only for a restore job. In addition, when running a Restore job + from the console, this value can be changed. + + If you use the {\bf Restore} command in the Console program, to start a + restore job, the {\bf bootstrap} file will be created automatically from + the files you select to be restored. + + For additional details of the {\bf bootstrap} file, please see + \ilink{Restoring Files with the Bootstrap File}{BootstrapChapter} chapter + of this manual. + +\label{writebootstrap} +\item [Write Bootstrap = \lt{}bootstrap-file-specification\gt{}] +\index[dir]{Write Bootstrap} +\index[dir]{Directive!Write Bootstrap} + The {\bf writebootstrap} directive specifies a file name where Bacula + will write a {\bf bootstrap} file for each Backup job run. This + directive applies only to Backup Jobs. If the Backup job is a Full + save, Bacula will erase any current contents of the specified file + before writing the bootstrap records. If the Job is an Incremental + or Differential + save, Bacula will append the current bootstrap record to the end of the + file. + + Using this feature, permits you to constantly have a bootstrap file that + can recover the current state of your system. Normally, the file + specified should be a mounted drive on another machine, so that if your + hard disk is lost, you will immediately have a bootstrap record + available. Alternatively, you should copy the bootstrap file to another + machine after it is updated. Note, it is a good idea to write a separate + bootstrap file for each Job backed up including the job that backs up + your catalog database. + + If the {\bf bootstrap-file-specification} begins with a vertical bar + (|), Bacula will use the specification as the name of a program to which + it will pipe the bootstrap record. It could for example be a shell + script that emails you the bootstrap record. + + On versions 1.39.22 or greater, before opening the file or executing the + specified command, Bacula performs + \ilink{character substitution}{character substitution} like in RunScript + directive. To automatically manage your bootstrap files, you can use + this in your {\bf JobDefs} resources: +\begin{verbatim} +JobDefs { + Write Bootstrap = "%c_%n.bsr" + ... +} +\end{verbatim} + + For more details on using this file, please see the chapter entitled + \ilink{The Bootstrap File}{BootstrapChapter} of this manual. + +\item [Client = \lt{}client-resource-name\gt{}] +\index[dir]{Client} +\index[dir]{Directive!Client} + The Client directive specifies the Client (File daemon) that will be used in + the current Job. Only a single Client may be specified in any one Job. The + Client runs on the machine to be backed up, and sends the requested files to + the Storage daemon for backup, or receives them when restoring. For + additional details, see the + \ilink{Client Resource section}{ClientResource2} of this chapter. + This directive is required. + +\item [FileSet = \lt{}FileSet-resource-name\gt{}] +\index[dir]{FileSet} +\index[dir]{FileSet} + The FileSet directive specifies the FileSet that will be used in the + current Job. The FileSet specifies which directories (or files) are to + be backed up, and what options to use (e.g. compression, ...). Only a + single FileSet resource may be specified in any one Job. For additional + details, see the \ilink{FileSet Resource section}{FileSetResource} of + this chapter. This directive is required. + +\item [Messages = \lt{}messages-resource-name\gt{}] +\index[dir]{Messages} +\index[dir]{Directive!Messages} + The Messages directive defines what Messages resource should be used for + this job, and thus how and where the various messages are to be + delivered. For example, you can direct some messages to a log file, and + others can be sent by email. For additional details, see the + \ilink{Messages Resource}{MessagesChapter} Chapter of this manual. This + directive is required. + +\item [Pool = \lt{}pool-resource-name\gt{}] +\index[dir]{Pool} +\index[dir]{Directive!Pool} + The Pool directive defines the pool of Volumes where your data can be + backed up. Many Bacula installations will use only the {\bf Default} + pool. However, if you want to specify a different set of Volumes for + different Clients or different Jobs, you will probably want to use + Pools. For additional details, see the \ilink{Pool Resource + section}{PoolResource} of this chapter. This directive is required. + +\item [Full Backup Pool = \lt{}pool-resource-name\gt{}] +\index[dir]{Full Backup Pool} +\index[dir]{Directive!Full Backup Pool} + The {\it Full Backup Pool} specifies a Pool to be used for Full backups. + It will override any Pool specification during a Full backup. This + directive is optional. + +\item [Differential Backup Pool = \lt{}pool-resource-name\gt{}] +\index[dir]{Differential Backup Pool} +\index[dir]{Directive!Differential Backup Pool} + The {\it Differential Backup Pool} specifies a Pool to be used for + Differential backups. It will override any Pool specification during a + Differential backup. This directive is optional. + +\item [Incremental Backup Pool = \lt{}pool-resource-name\gt{}] +\index[dir]{Incremental Backup Pool} +\index[dir]{Directive!Incremental Backup Pool} + The {\it Incremental Backup Pool} specifies a Pool to be used for + Incremental backups. It will override any Pool specification during an + Incremental backup. This directive is optional. + +\item [Schedule = \lt{}schedule-name\gt{}] +\index[dir]{Schedule} +\index[dir]{Directive!Schedule} + The Schedule directive defines what schedule is to be used for the Job. + The schedule in turn determines when the Job will be automatically + started and what Job level (i.e. Full, Incremental, ...) is to be run. + This directive is optional, and if left out, the Job can only be started + manually using the Console program. Although you may specify only a + single Schedule resource for any one job, the Schedule resource may + contain multiple {\bf Run} directives, which allow you to run the Job at + many different times, and each {\bf run} directive permits overriding + the default Job Level Pool, Storage, and Messages resources. This gives + considerable flexibility in what can be done with a single Job. For + additional details, see the \ilink{Schedule Resource + Chapter}{ScheduleResource} of this manual. + + +\item [Storage = \lt{}storage-resource-name\gt{}] +\index[dir]{Storage} +\index[dir]{Directive!Storage} + The Storage directive defines the name of the storage services where you + want to backup the FileSet data. For additional details, see the + \ilink{Storage Resource Chapter}{StorageResource2} of this manual. + The Storage resource may also be specified in the Job's Pool resource, + in which case the value in the Pool resource overrides any value + in the Job. This Storage resource definition is not required by either + the Job resource or in the Pool, but it must be specified in + one or the other, if not an error will result. + +\item [Max Start Delay = \lt{}time\gt{}] +\index[dir]{Max Start Delay} +\index[dir]{Directive!Max Start Delay} + The time specifies the maximum delay between the scheduled time and the + actual start time for the Job. For example, a job can be scheduled to + run at 1:00am, but because other jobs are running, it may wait to run. + If the delay is set to 3600 (one hour) and the job has not begun to run + by 2:00am, the job will be canceled. This can be useful, for example, + to prevent jobs from running during day time hours. The default is 0 + which indicates no limit. + +\item [Max Run Time = \lt{}time\gt{}] +\index[dir]{Max Run Time} +\index[dir]{Directive!Max Run Time} + The time specifies the maximum allowed time that a job may run, counted + from when the job starts, ({\bf not} necessarily the same as when the + job was scheduled). This directive is implemented in version 1.33 and + later. + +\item [Max Wait Time = \lt{}time\gt{}] +\index[dir]{Max Wait Time} +\index[dir]{Directive!Max Wait Time} + The time specifies the maximum allowed time that a job may block waiting + for a resource (such as waiting for a tape to be mounted, or waiting for + the storage or file daemons to perform their duties), counted from the + when the job starts, ({\bf not} necessarily the same as when the job was + scheduled). This directive is implemented only in version 1.33 and + later. + +\item [Incremental Max Wait Time = \lt{}time\gt{}] +\index[dir]{Incremental Max Wait Time} +\index[dir]{Directive!Incremental Max Wait Time} + The time specifies the maximum allowed time that an Incremental backup + job may block waiting for a resource (such as waiting for a tape to be + mounted, or waiting for the storage or file daemons to perform their + duties), counted from the when the job starts, ({\bf not} necessarily + the same as when the job was scheduled). Please note that if there is a + {\bf Max Wait Time} it may also be applied to the job. + +\item [Differential Max Wait Time = \lt{}time\gt{}] +\index[dir]{Differential Max Wait Time} +\index[dir]{Directive!Differential Max Wait Time} + The time specifies the maximum allowed time that a Differential backup + job may block waiting for a resource (such as waiting for a tape to be + mounted, or waiting for the storage or file daemons to perform their + duties), counted from the when the job starts, ({\bf not} necessarily + the same as when the job was scheduled). Please note that if there is a + {\bf Max Wait Time} it may also be applied to the job. + +\label{PreferMountedVolumes} +\item [Prefer Mounted Volumes = \lt{}yes|no\gt{}] +\index[dir]{Prefer Mounted Volumes} +\index[dir]{Directive!Prefer Mounted Volumes} + If the Prefer Mounted Volumes directive is set to {\bf yes} (default + yes), the Storage daemon is requested to select either an Autochanger or + a drive with a valid Volume already mounted in preference to a drive + that is not ready. This means that all jobs will attempt to append + to the same Volume (providing the Volume is appropriate -- right Pool, + ... for that job). If no drive with a suitable Volume is available, it + will select the first available drive. Note, any Volume that has + been requested to be mounted, will be considered valid as a mounted + volume by another job. This if multiple jobs start at the same time + and they all prefer mounted volumes, the first job will request the + mount, and the other jobs will use the same volume. + + If the directive is set to {\bf no}, the Storage daemon will prefer + finding an unused drive, otherwise, each job started will append to the + same Volume (assuming the Pool is the same for all jobs). Setting + Prefer Mounted Volumes to no can be useful for those sites + with multiple drive autochangers that prefer to maximize backup + throughput at the expense of using additional drives and Volumes. + This means that the job will prefer to use an unused drive rather + than use a drive that is already in use. + +\item [Prune Jobs = \lt{}yes|no\gt{}] +\index[dir]{Prune Jobs} +\index[dir]{Directive!Prune Jobs} + Normally, pruning of Jobs from the Catalog is specified on a Client by + Client basis in the Client resource with the {\bf AutoPrune} directive. + If this directive is specified (not normally) and the value is {\bf + yes}, it will override the value specified in the Client resource. The + default is {\bf no}. + + +\item [Prune Files = \lt{}yes|no\gt{}] +\index[dir]{Prune Files} +\index[dir]{Directive!Prune Files} + Normally, pruning of Files from the Catalog is specified on a Client by + Client basis in the Client resource with the {\bf AutoPrune} directive. + If this directive is specified (not normally) and the value is {\bf + yes}, it will override the value specified in the Client resource. The + default is {\bf no}. + +\item [Prune Volumes = \lt{}yes|no\gt{}] +\index[dir]{Prune Volumes} +\index[dir]{Directive!Prune Volumes} + Normally, pruning of Volumes from the Catalog is specified on a Client + by Client basis in the Client resource with the {\bf AutoPrune} + directive. If this directive is specified (not normally) and the value + is {\bf yes}, it will override the value specified in the Client + resource. The default is {\bf no}. + +\item [RunScript \{\lt{}body-of-runscript\gt{}\}] + \index[dir]{RunScript} + \index[dir]{Directive!Run Script} + + This directive is implemented in version 1.39.22 and later. + The RunScript directive behaves like a resource in that it + requires opening and closing braces around a number of directives + that make up the body of the runscript. + + The specified {\bf Command} (see below for details) is run as an + external program prior or after the current Job. This is optional. + + You can use following options may be specified in the body + of the runscript:\\ + +\begin{tabular}{|c|c|c|l} +Options & Value & Default & Information \\ +\hline +\hline +Runs On Success & Yes/No & {\it Yes} & Run command if JobStatus is successful\\ +\hline +Runs On Failure & Yes/No & {\it No} & Run command if JobStatus isn't successful\\ +\hline +Runs On Client & Yes/No & {\it Yes} & Run command on client\\ +\hline +Runs When & Before|After|Always & {\it Never} & When run commands\\ +\hline +Fail Job On Error & Yes/No & {\it Yes} & Fail job if script returns + something different from 0 \\ +\hline +Command & & & Path to your script\\ +\hline +\end{tabular} + \\ + + Any output sent by the command to standard output will be included in the + Bacula job report. The command string must be a valid program name or name + of a shell script. + + In addition, the command string is parsed then fed to the OS, + which means that the path will be searched to execute your specified + command, but there is no shell interpretation, as a consequence, if you + invoke complicated commands or want any shell features such as redirection + or piping, you must call a shell script and do it inside that script. + + Before submitting the specified command to the operating system, Bacula + performs character substitution of the following characters: + +\label{character substitution} +\footnotesize +\begin{verbatim} + %% = % + %c = Client's name + %d = Director's name + %e = Job Exit Status + %i = JobId + %j = Unique Job id + %l = Job Level + %n = Job name + %s = Since time + %t = Job type (Backup, ...) + %v = Volume name + +\end{verbatim} +\normalsize + +The Job Exit Status code \%e edits the following values: + +\index[dir]{Exit Status} +\begin{itemize} +\item OK +\item Error +\item Fatal Error +\item Canceled +\item Differences +\item Unknown term code +\end{itemize} + + Thus if you edit it on a command line, you will need to enclose + it within some sort of quotes. + + +You can use these following shortcuts:\\ + +\begin{tabular}{|c|c|c|c|c|c} +Keyword & RunsOnSuccess & RunsOnFailure & FailJobOnError & Runs On Client & RunsWhen \\ +\hline +Run Before Job & & & Yes & No & Before \\ +\hline +Run After Job & Yes & No & & No & After \\ +\hline +Run After Failed Job & No & Yes & & No & After \\ +\hline +Client Run Before Job & & & Yes & Yes & Before \\ +\hline +Client Run After Job & Yes & No & & Yes & After \\ +\end{tabular} + +Examples: +\begin{verbatim} +RunScript { + RunsWhen = Before + FailJobOnError = No + Command = "/etc/init.d/apache stop" +} + +RunScript { + RunsWhen = After + RunsOnFailure = yes + Command = "/etc/init.d/apache start" +} +\end{verbatim} + + {\bf Special Windows Considerations} + + In addition, for a Windows client on version 1.33 and above, please take + note that you must ensure a correct path to your script. The script or + program can be a .com, .exe or a .bat file. If you just put the program + name in then Bacula will search using the same rules that cmd.exe uses + (current directory, Bacula bin directory, and PATH). It will even try the + different extensions in the same order as cmd.exe. + The command can be anything that cmd.exe or command.com will recognize + as an executable file. + + However, if you have slashes in the program name then Bacula figures you + are fully specifying the name, so you must also explicitly add the three + character extension. + + The command is run in a Win32 environment, so Unix like commands will not + work unless you have installed and properly configured Cygwin in addition + to and separately from Bacula. + + The System \%Path\% will be searched for the command. (under the + environment variable dialog you have have both System Environment and + User Environment, we believe that only the System environment will be + available to bacula-fd, if it is running as a service.) + + System environment variables can be referenced with \%var\% and + used as either part of the command name or arguments. + + So if you have a script in the Bacula\\bin directory then the following lines + should work fine: + +\footnotesize +\begin{verbatim} + Client Run Before Job = systemstate +or + Client Run Before Job = systemstate.bat +or + Client Run Before Job = "systemstate" +or + Client Run Before Job = "systemstate.bat" +or + ClientRunBeforeJob = "\"C:/Program Files/Bacula/systemstate.bat\"" +\end{verbatim} +\normalsize + +The outer set of quotes is removed when the configuration file is parsed. +You need to escape the inner quotes so that they are there when the code +that parses the command line for execution runs so it can tell what the +program name is. + + +\footnotesize +\begin{verbatim} +ClientRunBeforeJob = "\"C:/Program Files/Software + Vendor/Executable\" /arg1 /arg2 \"foo bar\"" +\end{verbatim} +\normalsize + + The special characters +\begin{verbatim} +&<>()@^| +\end{verbatim} + will need to be quoted, + if they are part of a filename or argument. + + If someone is logged in, a blank "command" window running the commands + will be present during the execution of the command. + + Some Suggestions from Phil Stracchino for running on Win32 machines with + the native Win32 File daemon: + + \begin{enumerate} + \item You might want the ClientRunBeforeJob directive to specify a .bat + file which runs the actual client-side commands, rather than trying + to run (for example) regedit /e directly. + \item The batch file should explicitly 'exit 0' on successful completion. + \item The path to the batch file should be specified in Unix form: + + ClientRunBeforeJob = "c:/bacula/bin/systemstate.bat" + + rather than DOS/Windows form: + + ClientRunBeforeJob = + +"c:\textbackslash{}bacula\textbackslash{}bin\textbackslash{}systemstate.bat" + INCORRECT + \end{enumerate} + +For Win32, please note that there are certain limitations: + +ClientRunBeforeJob = "C:/Program Files/Bacula/bin/pre-exec.bat" + +Lines like the above do not work because there are limitations of +cmd.exe that is used to execute the command. +Bacula prefixes the string you supply with {\bf cmd.exe /c }. To test that +your command works you should type {\bf cmd /c "C:/Program Files/test.exe"} at a +cmd prompt and see what happens. Once the command is correct insert a +backslash (\textbackslash{}) before each double quote ("), and +then put quotes around the whole thing when putting it in +the director's .conf file. You either need to have only one set of quotes +or else use the short name and don't put quotes around the command path. + +Below is the output from cmd's help as it relates to the command line +passed to the /c option. + + + If /C or /K is specified, then the remainder of the command line after + the switch is processed as a command line, where the following logic is + used to process quote (") characters: + +\begin{enumerate} +\item + If all of the following conditions are met, then quote characters + on the command line are preserved: + \begin{itemize} + \item no /S switch. + \item exactly two quote characters. + \item no special characters between the two quote characters, + where special is one of: +\begin{verbatim} +&<>()@^| +\end{verbatim} + \item there are one or more whitespace characters between the + the two quote characters. + \item the string between the two quote characters is the name + of an executable file. + \end{itemize} + +\item Otherwise, old behavior is to see if the first character is + a quote character and if so, strip the leading character and + remove the last quote character on the command line, preserving + any text after the last quote character. + +\end{enumerate} + + +The following example of the use of the Client Run Before Job directive was +submitted by a user:\\ +You could write a shell script to back up a DB2 database to a FIFO. The shell +script is: + +\footnotesize +\begin{verbatim} + #!/bin/sh + # ===== backupdb.sh + DIR=/u01/mercuryd + + mkfifo $DIR/dbpipe + db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING & + sleep 1 +\end{verbatim} +\normalsize + +The following line in the Job resource in the bacula-dir.conf file: +\footnotesize +\begin{verbatim} + Client Run Before Job = "su - mercuryd -c \"/u01/mercuryd/backupdb.sh '%t' +'%l'\"" +\end{verbatim} +\normalsize + +When the job is run, you will get messages from the output of the script +stating that the backup has started. Even though the command being run is +backgrounded with \&, the job will block until the "db2 BACKUP DATABASE" +command, thus the backup stalls. + +To remedy this situation, the "db2 BACKUP DATABASE" line should be changed to +the following: + +\footnotesize +\begin{verbatim} + db2 BACKUP DATABASE mercuryd TO $DIR/dbpipe WITHOUT PROMPTING > $DIR/backup.log +2>&1 < /dev/null & +\end{verbatim} +\normalsize + +It is important to redirect the input and outputs of a backgrounded command to +/dev/null to prevent the script from blocking. + +\item [Run Before Job = \lt{}command\gt{}] +\index[dir]{Run Before Job} +\index[dir]{Directive!Run Before Job} +\index[dir]{Directive!Run Before Job} +The specified {\bf command} is run as an external program prior to running the +current Job. This directive is not required, but if it is defined, and if the +exit code of the program run is non-zero, the current Bacula job will be +canceled. + +\begin{verbatim} +Run Before Job = "echo test" +\end{verbatim} + it's equivalent to : +\begin{verbatim} +RunScript { + Command = "echo test" + RunsOnClient = No + RunsWhen = Before +} +\end{verbatim} + + Lutz Kittler has pointed out that using the RunBeforeJob directive can be a + simple way to modify your schedules during a holiday. For example, suppose + that you normally do Full backups on Fridays, but Thursday and Friday are + holidays. To avoid having to change tapes between Thursday and Friday when + no one is in the office, you can create a RunBeforeJob that returns a + non-zero status on Thursday and zero on all other days. That way, the + Thursday job will not run, and on Friday the tape you inserted on Wednesday + before leaving will be used. + +\item [Run After Job = \lt{}command\gt{}] +\index[dir]{Run After Job} +\index[dir]{Directive!Run After Job} + The specified {\bf command} is run as an external program if the current + job terminates normally (without error or without being canceled). This + directive is not required. If the exit code of the program run is + non-zero, Bacula will print a warning message. Before submitting the + specified command to the operating system, Bacula performs character + substitution as described above for the {\bf RunScript} directive. + + An example of the use of this directive is given in the + \ilink{Tips Chapter}{JobNotification} of this manual. + + See the {\bf Run After Failed Job} if you + want to run a script after the job has terminated with any + non-normal status. + +\item [Run After Failed Job = \lt{}command\gt{}] +\index[dir]{Run After Job} +\index[dir]{Directive!Run After Job} + The specified {\bf command} is run as an external program after the current + job terminates with any error status. This directive is not required. The + command string must be a valid program name or name of a shell script. If + the exit code of the program run is non-zero, Bacula will print a + warning message. Before submitting the specified command to the + operating system, Bacula performs character substitution as described above + for the {\bf RunScript} directive. Note, if you wish that your script + will run regardless of the exit status of the Job, you can use this : +\begin{verbatim} +RunScript { + Command = "echo test" + RunsWhen = After + RunsOnFailure = yes + RunsOnClient = no + RunsOnSuccess = yes # default, you can drop this line +} +\end{verbatim} + + An example of the use of this directive is given in the + \ilink{Tips Chapter}{JobNotification} of this manual. + + +\item [Client Run Before Job = \lt{}command\gt{}] +\index[dir]{Client Run Before Job} +\index[dir]{Directive!Client Run Before Job} + This directive is the same as {\bf Run Before Job} except that the + program is run on the client machine. The same restrictions apply to + Unix systems as noted above for the {\bf RunScript}. + +\item [Client Run After Job = \lt{}command\gt{}] + \index[dir]{Client Run After Job} + \index[dir]{Directive!Client Run After Job} + The specified {\bf command} is run on the client machine as soon + as data spooling is complete in order to allow restarting applications + on the client as soon as possible. . + + Note, please see the notes above in {\bf RunScript} + concerning Windows clients. + +\item [Rerun Failed Levels = \lt{}yes|no\gt{}] + \index[dir]{Rerun Failed Levels} + \index[dir]{Directive!Rerun Failed Levels} + If this directive is set to {\bf yes} (default no), and Bacula detects that + a previous job at a higher level (i.e. Full or Differential) has failed, + the current job level will be upgraded to the higher level. This is + particularly useful for Laptops where they may often be unreachable, and if + a prior Full save has failed, you wish the very next backup to be a Full + save rather than whatever level it is started as. + + There are several points that must be taken into account when using this + directive: first, a failed job is defined as one that has not terminated + normally, which includes any running job of the same name (you need to + ensure that two jobs of the same name do not run simultaneously); + secondly, the {\bf Ignore FileSet Changes} directive is not considered + when checking for failed levels, which means that any FileSet change will + trigger a rerun. + +\item [Spool Data = \lt{}yes|no\gt{}] + \index[dir]{Spool Data} + \index[dir]{Directive!Spool Data} + + If this directive is set to {\bf yes} (default no), the Storage daemon will + be requested to spool the data for this Job to disk rather than write it + directly to tape. Once all the data arrives or the spool files' maximum sizes + are reached, the data will be despooled and written to tape. Spooling data + prevents tape shoe-shine (start and stop) during + Incremental saves. If you are writing to a disk file using this option + will probably just slow down the backup jobs. + + NOTE: When this directive is set to yes, Spool Attributes is also + automatically set to yes. + +\item [Spool Attributes = \lt{}yes|no\gt{}] + \index[dir]{Spool Attributes} + \index[dir]{Directive!Spool Attributes} + \index[dir]{slow} + \index[general]{slow} + \index[dir]{Backups!slow} + \index[general]{Backups!slow} + The default is set to {\bf no}, which means that the File attributes are + sent by the Storage daemon to the Director as they are stored on tape. + However, if you want to avoid the possibility that database updates will + slow down writing to the tape, you may want to set the value to {\bf + yes}, in which case the Storage daemon will buffer the File attributes + and Storage coordinates to a temporary file in the Working Directory, + then when writing the Job data to the tape is completed, the attributes + and storage coordinates will be sent to the Director. + + NOTE: When Spool Data is set to yes, Spool Attributes is also + automatically set to yes. + +\item [Where = \lt{}directory\gt{}] + \index[dir]{Where} + \index[dir]{Directive!Where} + This directive applies only to a Restore job and specifies a prefix to + the directory name of all files being restored. This permits files to + be restored in a different location from which they were saved. If {\bf + Where} is not specified or is set to backslash ({\bf /}), the files will + be restored to their original location. By default, we have set {\bf + Where} in the example configuration files to be {\bf + /tmp/bacula-restores}. This is to prevent accidental overwriting of + your files. + +\item [Add Prefix = \lt{}directory\gt{}] + \label{confaddprefix} + \index[dir]{AddPrefix} + \index[dir]{Directive!AddPrefix} + This directive applies only to a Restore job and specifies a prefix to the + directory name of all files being restored. This will use \ilink{File + Relocation}{filerelocation} feature implemented in Bacula 2.1.8 or later. + +\item [Add Suffix = \lt{}extention\gt{}] + \index[dir]{AddSuffix} + \index[dir]{Directive!AddSuffix} + This directive applies only to a Restore job and specifies a suffix to all + files being restored. This will use \ilink{File Relocation}{filerelocation} + feature implemented in Bacula 2.1.8 or later. + + Using \texttt{Add Suffix=.old}, \texttt{/etc/passwd} will be restored to + \texttt{/etc/passwsd.old} + +\item [Strip Prefix = \lt{}directory\gt{}] + \index[dir]{StripPrefix} + \index[dir]{Directive!StripPrefix} + This directive applies only to a Restore job and specifies a prefix to remove + from the directory name of all files being restored. This will use the + \ilink{File Relocation}{filerelocation} feature implemented in Bacula 2.1.8 + or later. + + Using \texttt{Strip Prefix=/etc}, \texttt{/etc/passwd} will be restored to + \texttt{/passwd} + + Under Windows, if you want to restore \texttt{c:/files} to \texttt{d:/files}, + you can use : + +\begin{verbatim} + Strip Prefix = c: + Add Prefix = d: +\end{verbatim} + +\item [RegexWhere = \lt{}expressions\gt{}] + \index[dir]{RegexWhere} + \index[dir]{Directive!RegexWhere} + This directive applies only to a Restore job and specifies a regex filename + manipulation of all files being restored. This will use \ilink{File + Relocation}{filerelocation} feature implemented in Bacula 2.1.8 or later. + + For more informations about how use this option, see + \ilink{this}{useregexwhere}. + +\item [Replace = \lt{}replace-option\gt{}] + \index[dir]{Replace} + \index[dir]{Directive!Replace} + This directive applies only to a Restore job and specifies what happens + when Bacula wants to restore a file or directory that already exists. + You have the following options for {\bf replace-option}: + +\begin{description} + +\item [always] + \index[dir]{always} + when the file to be restored already exists, it is deleted and then + replaced by the copy that was backed up. + +\item [ifnewer] +\index[dir]{ifnewer} + if the backed up file (on tape) is newer than the existing file, the + existing file is deleted and replaced by the back up. + +\item [ifolder] + \index[dir]{ifolder} + if the backed up file (on tape) is older than the existing file, the + existing file is deleted and replaced by the back up. + +\item [never] + \index[dir]{never} + if the backed up file already exists, Bacula skips restoring this file. +\end{description} + +\item [Prefix Links=\lt{}yes|no\gt{}] + \index[dir]{Prefix Links} + \index[dir]{Directive!Prefix Links} + If a {\bf Where} path prefix is specified for a recovery job, apply it + to absolute links as well. The default is {\bf No}. When set to {\bf + Yes} then while restoring files to an alternate directory, any absolute + soft links will also be modified to point to the new alternate + directory. Normally this is what is desired -- i.e. everything is self + consistent. However, if you wish to later move the files to their + original locations, all files linked with absolute names will be broken. + +\item [Maximum Concurrent Jobs = \lt{}number\gt{}] + \index[dir]{Maximum Concurrent Jobs} + \index[dir]{Directive!Maximum Concurrent Jobs} + where \lt{}number\gt{} is the maximum number of Jobs from the current + Job resource that can run concurrently. Note, this directive limits + only Jobs with the same name as the resource in which it appears. Any + other restrictions on the maximum concurrent jobs such as in the + Director, Client, or Storage resources will also apply in addition to + the limit specified here. The default is set to 1, but you may set it + to a larger number. We strongly recommend that you read the WARNING + documented under \ilink{ Maximum Concurrent Jobs}{DirMaxConJobs} in the + Director's resource. + +\item [Reschedule On Error = \lt{}yes|no\gt{}] + \index[dir]{Reschedule On Error} + \index[dir]{Directive!Reschedule On Error} + If this directive is enabled, and the job terminates in error, the job + will be rescheduled as determined by the {\bf Reschedule Interval} and + {\bf Reschedule Times} directives. If you cancel the job, it will not + be rescheduled. The default is {\bf no} (i.e. the job will not be + rescheduled). + + This specification can be useful for portables, laptops, or other + machines that are not always connected to the network or switched on. + +\item [Reschedule Interval = \lt{}time-specification\gt{}] + \index[dir]{Reschedule Interval} + \index[dir]{Directive!Reschedule Interval} + If you have specified {\bf Reschedule On Error = yes} and the job + terminates in error, it will be rescheduled after the interval of time + specified by {\bf time-specification}. See \ilink{the time + specification formats}{Time} in the Configure chapter for details of + time specifications. If no interval is specified, the job will not be + rescheduled on error. + +\item [Reschedule Times = \lt{}count\gt{}] + \index[dir]{Reschedule Times} + \index[dir]{Directive!Reschedule Times} + This directive specifies the maximum number of times to reschedule the + job. If it is set to zero (the default) the job will be rescheduled an + indefinite number of times. + +\item [Run = \lt{}job-name\gt{}] + \index[dir]{Run} + \index[dir]{Directive!Run} + \index[dir]{Clone a Job} + The Run directive (not to be confused with the Run option in a + Schedule) allows you to start other jobs or to clone jobs. By using the + cloning keywords (see below), you can backup + the same data (or almost the same data) to two or more drives + at the same time. The {\bf job-name} is normally the same name + as the current Job resource (thus creating a clone). However, it + may be any Job name, so one job may start other related jobs. + + The part after the equal sign must be enclosed in double quotes, + and can contain any string or set of options (overrides) that you + can specify when entering the Run command from the console. For + example {\bf storage=DDS-4 ...}. In addition, there are two special + keywords that permit you to clone the current job. They are {\bf level=\%l} + and {\bf since=\%s}. The \%l in the level keyword permits + entering the actual level of the current job and the \%s in the since + keyword permits putting the same time for comparison as used on the + current job. Note, in the case of the since keyword, the \%s must be + enclosed in double quotes, and thus they must be preceded by a backslash + since they are already inside quotes. For example: + +\begin{verbatim} + run = "Nightly-backup level=%l since=\"%s\" storage=DDS-4" +\end{verbatim} + + A cloned job will not start additional clones, so it is not + possible to recurse. + + Please note that all cloned jobs, as specified in the Run directives are + submitted for running before the original job is run (while it is being + initialized). This means that any clone job will actually start before + the original job, and may even block the original job from starting + until the original job finishes unless you allow multiple simultaneous + jobs. Even if you set a lower priority on the clone job, if no other + jobs are running, it will start before the original job. + + If you are trying to prioritize jobs by using the clone feature (Run + directive), you will find it much easier to do using a RunScript + resource, or a RunBeforeJob directive. + +\label{Priority} +\item [Priority = \lt{}number\gt{}] + \index[dir]{Priority} + \index[dir]{Directive!Priority} + This directive permits you to control the order in which your jobs will + be run by specifying a positive non-zero number. The higher the number, + the lower the job priority. Assuming you are not running concurrent jobs, + all queued jobs of priority 1 will run before queued jobs of priority 2 + and so on, regardless of the original scheduling order. + + The priority only affects waiting jobs that are queued to run, not jobs + that are already running. If one or more jobs of priority 2 are already + running, and a new job is scheduled with priority 1, the currently + running priority 2 jobs must complete before the priority 1 job is run. + + The default priority is 10. + + If you want to run concurrent jobs you should + keep these points in mind: + +\begin{itemize} +\item See \ilink{Running Concurrent Jobs}{ConcurrentJobs} on how to setup + concurrent jobs. + +\item Bacula concurrently runs jobs of only one priority at a time. It + will not simultaneously run a priority 1 and a priority 2 job. + +\item If Bacula is running a priority 2 job and a new priority 1 job is + scheduled, it will wait until the running priority 2 job terminates even + if the Maximum Concurrent Jobs settings would otherwise allow two jobs + to run simultaneously. + +\item Suppose that bacula is running a priority 2 job and a new priority 1 + job is scheduled and queued waiting for the running priority 2 job to + terminate. If you then start a second priority 2 job, the waiting + priority 1 job will prevent the new priority 2 job from running + concurrently with the running priority 2 job. That is: as long as there + is a higher priority job waiting to run, no new lower priority jobs will + start even if the Maximum Concurrent Jobs settings would normally allow + them to run. This ensures that higher priority jobs will be run as soon + as possible. +\end{itemize} + +If you have several jobs of different priority, it may not best to start +them at exactly the same time, because Bacula must examine them one at a +time. If by Bacula starts a lower priority job first, then it will run +before your high priority jobs. If you experience this problem, you may +avoid it by starting any higher priority jobs a few seconds before lower +priority ones. This insures that Bacula will examine the jobs in the +correct order, and that your priority scheme will be respected. + +\label{WritePartAfterJob} +\item [Write Part After Job = \lt{}yes|no\gt{}] +\index[dir]{Write Part After Job} +\index[dir]{Directive!Write Part After Job} + This directive is only implemented in version 1.37 and later. + If this directive is set to {\bf yes} (default {\bf no}), a new part file + will be created after the job is finished. + + It should be set to {\bf yes} when writing to devices that require mount + (for example DVD), so you are sure that the current part, containing + this job's data, is written to the device, and that no data is left in + the temporary file on the hard disk. However, on some media, like DVD+R + and DVD-R, a lot of space (about 10Mb) is lost every time a part is + written. So, if you run several jobs each after another, you could set + this directive to {\bf no} for all jobs, except the last one, to avoid + wasting too much space, but to ensure that the data is written to the + medium when all jobs are finished. + + This directive is ignored with tape and FIFO devices. + +\item [Heartbeat Interval = \lt{}time-interval\gt{}] + \index[dir]{Heartbeat Interval} + \index[dir]{Directive!Heartbeat} + This directive is optional and if specified will cause the Director to + set a keepalive interval (heartbeat) in seconds on each of the sockets + it opens for the Client resource. This value will override any + specified at the Director level. It is implemented only on systems + (Linux, ...) that provide the {\bf setsockopt} TCP\_KEEPIDLE function. + The default value is zero, which means no change is made to the socket. + +\end{description} + +The following is an example of a valid Job resource definition: + +\footnotesize +\begin{verbatim} +Job { + Name = "Minou" + Type = Backup + Level = Incremental # default + Client = Minou + FileSet="Minou Full Set" + Storage = DLTDrive + Pool = Default + Schedule = "MinouWeeklyCycle" + Messages = Standard +} +\end{verbatim} +\normalsize + +\section{The JobDefs Resource} +\label{JobDefsResource} +\index[general]{JobDefs Resource} +\index[general]{Resource!JobDefs} + +The JobDefs resource permits all the same directives that can appear in a Job +resource. However, a JobDefs resource does not create a Job, rather it can be +referenced within a Job to provide defaults for that Job. This permits you to +concisely define several nearly identical Jobs, each one referencing a JobDefs +resource which contains the defaults. Only the changes from the defaults need to +be mentioned in each Job. + +\section{The Schedule Resource} +\label{ScheduleResource} +\index[general]{Resource!Schedule} +\index[general]{Schedule Resource} + +The Schedule resource provides a means of automatically scheduling a Job as +well as the ability to override the default Level, Pool, Storage and Messages +resources. If a Schedule resource is not referenced in a Job, the Job can only +be run manually. In general, you specify an action to be taken and when. + +\begin{description} + +\item [Schedule] +\index[dir]{Schedule} +\index[dir]{Directive!Schedule} + Start of the Schedule directives. No {\bf Schedule} resource is + required, but you will need at least one if you want Jobs to be + automatically started. + +\item [Name = \lt{}name\gt{}] + \index[dir]{Name} + \index[dir]{Directive!Name} + The name of the schedule being defined. The Name directive is required. + +\item [Run = \lt{}Job-overrides\gt{} \lt{}Date-time-specification\gt{}] + \index[dir]{Run} + \index[dir]{Directive!Run} + The Run directive defines when a Job is to be run, and what overrides if + any to apply. You may specify multiple {\bf run} directives within a + {\bf Schedule} resource. If you do, they will all be applied (i.e. + multiple schedules). If you have two {\bf Run} directives that start at + the same time, two Jobs will start at the same time (well, within one + second of each other). + + The {\bf Job-overrides} permit overriding the Level, the Storage, the + Messages, and the Pool specifications provided in the Job resource. In + addition, the FullPool, the IncrementalPool, and the DifferentialPool + specifications permit overriding the Pool specification according to + what backup Job Level is in effect. + + By the use of overrides, you may customize a particular Job. For + example, you may specify a Messages override for your Incremental + backups that outputs messages to a log file, but for your weekly or + monthly Full backups, you may send the output by email by using a + different Messages override. + + {\bf Job-overrides} are specified as: {\bf keyword=value} where the + keyword is Level, Storage, Messages, Pool, FullPool, DifferentialPool, + or IncrementalPool, and the {\bf value} is as defined on the respective + directive formats for the Job resource. You may specify multiple {\bf + Job-overrides} on one {\bf Run} directive by separating them with one or + more spaces or by separating them with a trailing comma. For example: + +\begin{description} + +\item [Level=Full] + \index[dir]{Level} + \index[dir]{Directive!Level} + is all files in the FileSet whether or not they have changed. + +\item [Level=Incremental] + \index[dir]{Level} + \index[dir]{Directive!Level} + is all files that have changed since the last backup. + +\item [Pool=Weekly] + \index[dir]{Pool} + \index[dir]{Directive!Pool} + specifies to use the Pool named {\bf Weekly}. + +\item [Storage=DLT\_Drive] + \index[dir]{Storage} + \index[dir]{Directive!Storage} + specifies to use {\bf DLT\_Drive} for the storage device. + +\item [Messages=Verbose] + \index[dir]{Messages} + \index[dir]{Directive!Messages} + specifies to use the {\bf Verbose} message resource for the Job. + +\item [FullPool=Full] + \index[dir]{FullPool} + \index[dir]{Directive!FullPool} + specifies to use the Pool named {\bf Full} if the job is a full backup, or +is +upgraded from another type to a full backup. + +\item [DifferentialPool=Differential] + \index[dir]{DifferentialPool} + \index[dir]{Directive!DifferentialPool} + specifies to use the Pool named {\bf Differential} if the job is a + differential backup. + +\item [IncrementalPool=Incremental] + \index[dir]{IncrementalPool} + \index[dir]{Directive!IncrementalPool} + specifies to use the Pool named {\bf Incremental} if the job is an +incremental backup. + +\item [SpoolData=yes|no] + \index[dir]{SpoolData} + \index[dir]{Directive!SpoolData} + tells Bacula to request the Storage daemon to spool data to a disk file + before writing it to the Volume (normally a tape). Thus the data is + written in large blocks to the Volume rather than small blocks. This + directive is particularly useful when running multiple simultaneous + backups to tape. It prevents interleaving of the job data and reduces + or eliminates tape drive stop and start commonly known as "shoe-shine". + +\item [SpoolSize={\it bytes}] + \index[dir]{SpoolSize} + \index[dir]{Directive!SpoolSize} + where the bytes specify the maximum spool size for this job. + The default is take from Device Maximum Spool Size limit. + This directive is available only in Bacula version 2.3.5 or + later. + +\item [WritePartAfterJob=yes|no] + \index[dir]{WritePartAfterJob} + \index[dir]{Directive!WritePartAfterJob} + tells Bacula to request the Storage daemon to write the current part + file to the device when the job is finished (see \ilink{Write Part After + Job directive in the Job resource}{WritePartAfterJob}). Please note, + this directive is implemented only in version 1.37 and later. The + default is yes. We strongly recommend that you keep this set to yes + otherwise, when the last job has finished one part will remain in the + spool file and restore may or may not work. + +\end{description} + +{\bf Date-time-specification} determines when the Job is to be run. The +specification is a repetition, and as a default Bacula is set to run a job at +the beginning of the hour of every hour of every day of every week of every +month of every year. This is not normally what you want, so you must specify +or limit when you want the job to run. Any specification given is assumed to +be repetitive in nature and will serve to override or limit the default +repetition. This is done by specifying masks or times for the hour, day of the +month, day of the week, week of the month, week of the year, and month when +you want the job to run. By specifying one or more of the above, you can +define a schedule to repeat at almost any frequency you want. + +Basically, you must supply a {\bf month}, {\bf day}, {\bf hour}, and {\bf +minute} the Job is to be run. Of these four items to be specified, {\bf day} +is special in that you may either specify a day of the month such as 1, 2, +... 31, or you may specify a day of the week such as Monday, Tuesday, ... +Sunday. Finally, you may also specify a week qualifier to restrict the +schedule to the first, second, third, fourth, or fifth week of the month. + +For example, if you specify only a day of the week, such as {\bf Tuesday} the +Job will be run every hour of every Tuesday of every Month. That is the {\bf +month} and {\bf hour} remain set to the defaults of every month and all +hours. + +Note, by default with no other specification, your job will run at the +beginning of every hour. If you wish your job to run more than once in any +given hour, you will need to specify multiple {\bf run} specifications each +with a different minute. + +The date/time to run the Job can be specified in the following way in +pseudo-BNF: + +\footnotesize +\begin{verbatim} + = on + = at + = 1st | 2nd | 3rd | 4th | 5th | first | + second | third | fourth | fifth + = sun | mon | tue | wed | thu | fri | sat | + sunday | monday | tuesday | wednesday | + thursday | friday | saturday + = w00 | w01 | ... w52 | w53 + = jan | feb | mar | apr | may | jun | jul | + aug | sep | oct | nov | dec | january | + february | ... | december + = daily + = weekly + = monthly + = hourly + = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 + = | +<12hour> = 0 | 1 | 2 | ... 12 + = 0 | 1 | 2 | ... 23 + = 0 | 1 | 2 | ... 59 + = 1 | 2 | ... 31 +
'.$index unless ($index =~ /^\s*/); + $index_number++; # KEC. + if ($SHORT_INDEX) { + print "(compact version with Legend)"; + local($num) = ( $index =~ s/\ 50 ) { + s/$idx_mark/$preindex
\n$index\n<\/DL>$preindex/o; + } else { + s/$idx_mark/$preindex
\n$index\n<\/DL>/o; + } + } else { + s/$idx_mark/
\n$index\n<\/DL>/o; } + } +} +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# The bibliography and the index should be treated as separate sections +# in their own HTML files. The \bibliography{} command acts as a sectioning command +# that has the desired effect. But when the bibliography is constructed +# manually using the thebibliography environment, or when using the +# theindex environment it is not possible to use the normal sectioning +# mechanism. This subroutine inserts a \bibliography{} or a dummy +# \textohtmlindex command just before the appropriate environments +# to force sectioning. +sub add_bbl_and_idx_dummy_commands { + local($id) = $global{'max_id'}; + + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg; + ## if ($bbl_cnt == 1) { + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo; + #} + $global{'max_id'} = $id; + # KEC. Modified to global substitution to place multiple index tokens. + s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go; + # KEC. Modified to pick up the optional argument to \printindex + s/[\\]printindex\s*(\[.*?\])?/ + do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego; + &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands); +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# For each textohtmlindex mark found, determine the index titles and headers. +# We place the index ref in the header so the proper index can be generated later. +# For the default index, the index ref is blank. +# +# One problem is that this routine is called twice.. Once for processing the +# command as originally seen, and once for processing the command when +# doing the name for the index file. We can detect that by looking at the +# id numbers (or ref) surrounding the \theindex command, and not incrementing +# index_number unless a new id (or ref) is seen. This has the side effect of +# having to unconventionally start the index_number at -1. But it works. +# +# Gets the title from the list of indices. +# If this is the first index, save the title in $first_idx_file. This is what's referenced +# in the navigation buttons. +# Increment the index_number for next time. +# If the indexname command is defined or a newcommand defined for indexname, do it. +# Save the index TITLE in the toc +# Save the first_idx_file into the idxfile. This goes into the nav buttons. +# Build index_labels if needed. +# Create the index headings and put them in the output stream. + +{ my $index_number = 0; # Will be incremented before use. + my $first_idx_file; # Static + my $no_increment = 0; + +sub do_cmd_textohtmlindex { + local($_) = @_; + my ($idxref,$idxnum,$index_name); + + # We get called from make_name with the first argument = "\001noincrement". This is a sign + # to not increment $index_number the next time we are called. We get called twice, once + # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name + # but doesn't use the result so we get called a second time by process_command. This works fine + # except for cases where there are multiple indices except if they aren't named, which is the case + # when the index is inserted by an include command in latex. In these cases we are only able to use + # the index number to decide which index to draw from, and we don't know how to increment that index + # number if we get called a variable number of times for the same index, as is the case between + # making html (one output file) and web (multiple output files) output formats. + if (/\001noincrement/) { + $no_increment = 1; + return; + } + + # Remove (but save) the index reference + s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e; + + # If we have an $idxref, the index name was specified. In this case, we have all the + # information we need to carry on. Otherwise, we need to get the idxref + # from the $index_number and set the name to "Index". + if ($idxref) { + $index_name = $indices{'title'}{$idxref}; + } else { + if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) { + $index_name = $indices{'title'}{$idxref}; + } else { + $idxref = ''; + $index_name = "Index"; + } + } + + $idx_title = "Index"; # The name displayed in the nav bar text. + + # Only set $idxfile if we are at the first index. This will point the + # navigation panel to the first index file rather than the last. + $first_idx_file = $CURRENT_FILE if ($index_number == 0); + $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar. + $toc_sec_title = $index_name; # Index link text in the toc. + $TITLE = $toc_sec_title; # Title for this index, from which its filename is built. + if (%index_labels) { &make_index_labels(); } + if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); } + else { $preindex = ''; } + local $idx_head = $section_headings{'textohtmlindex'}; + local($heading) = join('' + , &make_section_heading($TITLE, $idx_head) + , $idx_mark, "\002", $idxref, "\002" ); + local($pre,$post) = &minimize_open_tags($heading); + $index_number++ unless ($no_increment); + $no_increment = 0; + join('',"
\n" , $pre, $_); +} +} + +# Returns an index key, given the key passed as the first argument. +# Not modified for multiple indices. +sub add_idx_key { + local($key) = @_; + local($index, $next); + if (($index{$key} eq '@' )&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { $index .= "

\n
".&print_key."\n
"; } + else { $index .= "

\n
".&print_key."\n
"; } + } elsif (($index{$key})&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { + $next = "
".&print_key."\n : ". &print_idx_links; + } else { + $next = "
".&print_key."\n
". &print_idx_links; + } + $index .= $next."\n"; + $index_printed{$key} = 1; + } + + if ($sub_index{$key}) { + local($subkey, @subkeys, $subnext, $subindex); + @subkeys = sort(split("\004", $sub_index{$key})); + if ($SHORT_INDEX) { + $index .= "
".&print_key unless $index_printed{$key}; + $index .= "
\n"; + } else { + $index .= "
".&print_key."\n
" unless $index_printed{$key}; + $index .= "
\n"; + } + foreach $subkey (@subkeys) { + $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey}); + } + $index .= "
\n"; + } + return $index; +} + +1; # Must be present as the last line. diff --git a/docs/manuals/fr/install/install.css b/docs/manuals/fr/install/install.css new file mode 100644 index 00000000..d1824aff --- /dev/null +++ b/docs/manuals/fr/install/install.css @@ -0,0 +1,30 @@ +/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */ +.MATH { font-family: "Century Schoolbook", serif; } +.MATH I { font-family: "Century Schoolbook", serif; font-style: italic } +.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold } + +/* implement both fixed-size and relative sizes */ +SMALL.XTINY { font-size : xx-small } +SMALL.TINY { font-size : x-small } +SMALL.SCRIPTSIZE { font-size : smaller } +SMALL.FOOTNOTESIZE { font-size : small } +SMALL.SMALL { } +BIG.LARGE { } +BIG.XLARGE { font-size : large } +BIG.XXLARGE { font-size : x-large } +BIG.HUGE { font-size : larger } +BIG.XHUGE { font-size : xx-large } + +/* heading styles */ +H1 { } +H2 { } +H3 { } +H4 { } +H5 { } + +/* mathematics styles */ +DIV.displaymath { } /* math displays */ +TD.eqno { } /* equation-number cells */ + + +/* document-specific styles come next */ diff --git a/docs/manuals/fr/install/install.tex b/docs/manuals/fr/install/install.tex new file mode 100644 index 00000000..3b325fe3 --- /dev/null +++ b/docs/manuals/fr/install/install.tex @@ -0,0 +1,95 @@ +%% +%% +%% The following characters must be preceded by a backslash +%% to be entered as printable characters: +%% +%% # $ % & ~ _ ^ \ { } +%% + +\documentclass[11pt,a4paper]{book} +\usepackage{html} +\usepackage{float} +\usepackage{graphicx} +\usepackage{bacula} +\usepackage{longtable} +\usepackage{makeidx} +\usepackage{index} +\usepackage{setspace} +\usepackage{hyperref} +\usepackage{url} + + +\makeindex +\newindex{dir}{ddx}{dnd}{Director Index} +\newindex{fd}{fdx}{fnd}{File Daemon Index} +\newindex{sd}{sdx}{snd}{Storage Daemon Index} +\newindex{console}{cdx}{cnd}{Console Index} +\newindex{general}{idx}{ind}{General Index} + +\sloppy + +\begin{document} +\sloppy + +\newfont{\bighead}{cmr17 at 36pt} +\parskip 10pt +\parindent 0pt + +\title{\includegraphics{./bacula-logo.eps} \\ \bigskip + \Huge{Bacula Installation and Configuration Guide} + \begin{center} + \large{It comes in the night and sucks + the essence from your computers. } + \end{center} +} + + +\author{Kern Sibbald} +\date{\vspace{1.0in}\today \\ + This manual documents Bacula version \input{version} \\ + \vspace{0.2in} + Copyright \copyright 1999-2007, Free Software Foundation Europe + e.V. \\ + \vspace{0.2in} + Permission is granted to copy, distribute and/or modify this document under the terms of the + GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU Free Documentation License". +} + +\maketitle + +\clearpage +\tableofcontents +\clearpage +\listoffigures +\clearpage +\listoftables +\clearpage + +\include{quickstart} +\include{installation} +\include{critical} +\include{configure} +\include{dirdconf} +\include{filedconf} +\include{storedconf} +\include{messagesres} +\include{consoleconf} +\include{monitorconf} +\include{security} +\include{fdl} + + +% The following line tells link_resolver.pl to not include these files: +% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main + +% pull in the index +\clearpage +\printindex[general] +\printindex[dir] +\printindex[fd] +\printindex[sd] +\printindex[console] + +\end{document} diff --git a/docs/manuals/fr/install/installation.tex b/docs/manuals/fr/install/installation.tex new file mode 100644 index 00000000..12989c2c --- /dev/null +++ b/docs/manuals/fr/install/installation.tex @@ -0,0 +1,1518 @@ +%% +%% + +\chapter{Installer Bacula} +\label{_ChapterStart17} +\index[general]{Installer Bacula } +\index[general]{Bacula!Installer } +\addcontentsline{toc}{section}{Installer Bacula} + +\section{Pr\'erequis} +\index[general]{Pr\'erequis } +\addcontentsline{toc}{section}{Pr\'erequis} + +En g\'en\'eral, il vous faudra les sources de la version courante de Bacula, +et si vous souhaitez ex\'ecuter un client Windows, vous aurez besoin de la +version binaire du client Bacula pour Windows. Par ailleurs, Bacula a besoin +de certains paquetages externes (tels {\bf SQLite}, {\bf MySQL} ou {\bf +PostgreSQL}) pour compiler correctement en accord avec les options que vous +aurez choisies. Pour vous simplifier la t\^ache, nous avons combin\'e +plusieurs de ces programmes dans deux paquetages {\bf depkgs} (paquetages de +d\'ependances). Ceci peut vous simplifier la vie en vous fournissant tous les +paquets n\'ecessaires plut\^ot que de vous contraindre \`a les trouver sur la +Toile, les charger et installer. + +\section{Distribution des fichiers source} +\index[general]{fichiers source} +\index[general]{distrribution fichiers} +\addcontentsline{toc}{section}{Distribution des fichiers source} +A partir de la version 1.38.0, le code source est \'eclat\'e en quatre +fichiers tar correspondant \`a quatre modules diff\'erents dans le CVS +Bacula. Ces fichiers sont : + +\begin{description} +\item [bacula-1.38.0.tar.gz] + Il s'agit de la distribution primaire de Bacula. Pour chaque nouvelle + version, le num\'ero de version (ici, 1.38.0) sera mise \`a jour. + +\item [bacula-docs-1.38.0.tar.gz] + Ce fichier contient une copie du r\'epertoire docs, avec les documents + pr\'e-construits : R\'epertoire html anglais, fichier html unique et + fichier pdf. Les traductions allemande et fran\c {c}aise sont en cours mais + ne sont pas pr\'e-construites. + +\item [bacula-gui-1.38.0.tar.gz] + Ce fichier contient les programmes graphique en dehors du coeur + de l'application. Actuellement, il contient bacula-web, un programme + PHP pour produire une vue d'ensemble des statuts de vos jobs + Bacula consultable dans un navigateur ; et bimagemgr, un programme + qui permet de graver des images de CDROMS depuis un navigateur avec + les volumes Bacula. + +\item [bacula-rescue-1.8.1.tar.gz] + Ce fichier contient le code du CDROM de secours Bacula. Notez + que le num\'ero de version de ce paquetage n'est pas li\'e \`a celui + de Bacula. En utilisant ce code, vous pouvez graver un CDROM contenant + la configuration de votre syst\`eme et une version statiquement li\'ee du + File Daemon. Ceci peut vous permettre de repartitionner et reformater + ais\'ement vos disques durs et de recharger votre syst\`eme avec Bacula + en cas de d\'efaillance du disque dur. + +\item [winbacula-1.38.0.exe] + Ce fichier est l'installeur 32 bits Windows pour l'installation du + client Windows (File Daemon) sur une machine Windows. + A partir de la version 1.39.20, cet exécutable contiendra aussi + le Director Win32 et le Storage Daemon Win32. +\end{description} + +\label{upgrading1} + +\section{Mettre Bacula \`a jour} +\index[general]{Mettre Bacula \`a jour } +\index[general]{Jour!Mettre Bacula \`a } +\addcontentsline{toc}{section}{Mettre Bacula \`a jour} + +Si vous faites une mise \`a jour de Bacula, vous devriez d'abord lire +attentivement les ReleaseNotes de toutes les versions entre votre version +install\'ee et celle vers laquelle vous souhaitez mettre \`a jour. Si la base +de donn\'ees du catalogue a \'et\'e mise \`a jour (c'est presque toujours le cas +à chaque nouvelle version majeure), vous devrez soit +r\'einitialiser votre base de donn\'ees et repartir de z\'ero, soit en +sauvegarder une copie au format ASCII avant de proc\'eder \`a sa mise \`a +jour. Ceci est normalement fait lorsque Bacula est compil\'e et install\'e par : + +\begin{verbatim} +cd (default /etc/bacula) +./update_bacula_tables +\end{verbatim} + +Ce script de mise \`a jour peut aussi \^etre trouv\'e dans le r\'epertoire +src/cats des sources de Bacula. + +S'il y a eu plusieurs mises \`a jour de la base de donn\'ees entre votre +version et celle vers laquelle vous souhaitez \'evoluer, il faudra appliquer +chaque script de mise \`a jour de base de donn\'ees. Vous pouvez trouver tous +les anciens scripts de mise \`a jour dans le r\'epertoire {\bf upgradedb} des +sources de Bacula. Il vous faudra \'editer ces scripts pour qu'ils +correspondent \`a votre configuration. Le script final, s'il y en a un, sera +dans le r\'epertoire {\bf src/cats} comme indiqu\'e dans la ReleaseNote. + +Si vous migrez d'une version majeure vers une autre, vous devrez remplacer +tous vos composants ({\it daemons}) en m\^eme temps car, g\'en\'eralement, le +protocole inter-{\it daemons} aura chang\'e. Par contre, entre deux versions +mineures d'une m\^eme majeure (par exemple les versions 1.32.x), \`a moins +d'un bug, le protocole inter-{\it daemons} ne changera pas. Si cela vous +semble confus, lisez simplement les ReleaseNotes tr\`es attentivement, elles +signaleront si les {\it daemons} doivent \^etre mis \`a jour simultan\'ement. + +Enfin, notez qu'il n'est g\'en\'eralement pas n\'ecessaire d'utiliser +{\bf make uninstall} avant de proc\'eder \`a une mise \`a jour. En fait, si vous le +faites vous effacerez probablement vos fichiers de configuration, ce qui +pourrait \^etre d\'esastreux. La proc\'edure normale de mise \`a jour est simplement : +\begin{verbatim} +./configure (your options) +make +make install +\end{verbatim} + + En principe, aucun de vos fichiers .conf ou .sql ne devrait \^etre \'ecras\'e, + et vous devez exécuter les deux commandes {\bf make} et {\bf make install}. + {\bf make install} sans un {\bf make} préalable ne fonctionnera pas. + +Pour plus d'informations sur les mises \`a jour, veuillez consulter la partie +\ilink{Upgrading Bacula Versions}{upgrading} du chapitre Astuces de ce manuel + +\section{Paquetage de D\'ependences} +\label{Dependency} +\index[general]{Paquetage de D\'ependences} +\index[general]{Paquetage!D\'ependences} +\addcontentsline{toc}{section}{Paquetage de D\'ependences} + +Comme nous l'\'evoquions plus haut, nous avons combin\'e une s\'erie de +programmes dont Bacula peut avoir besoin dans les paquets {\bf depkgs} et {\bf +depkgs1}. Vous pouvez, bien sur, obtenir les paquets les plus r\'ecents +directement des auteurs. Le fichier README dans chaque paquet indique o\`u les +trouver. Pourtant, il faut noter que nous avons test\'e la compatibilit\'e des +paquets contenus dans les fichiers depkgs avec Bacula. + +Vous pouvez, bien sur, obtenir les dernieres versions de ces paquetages de +leurs auteurs. Les r\'ef\'erences n\'ecessaires figurent dans le README de +chaque paquet. Quoi qu'il en soit, soyez conscient du fait que nous avons +test\'e la compatibilit\'e des paquetages des fichiers depkgs. + +Typiquement, un paquetage de d\'ependances sera nomm\'e {\bf +depkgs-ddMMMyy.tar.gz} et {\bf depkgs1-ddMMMyy.tar.gz} o\`u {\bf dd} est le +jour o\`u n'ous l'avons publi\'e, {\bf MMM} l'abbr\'eviation du mois et {\bf +yy} l'ann\'ee. Par exemple: {\bf depkgs-07Apr02.tar.gz}. Pour installer et +construire ce paquetage (s'il est requis), vous devez: + +\begin{enumerate} +\item Cr\'eer un r\'epertoire {\bf bacula}, dans lequel vous placerez les + sources de Bacula et le paquetage de d\'ependances. +\item D\'esarchiver le {\bf depkg} dans le r\'epertoire {\bf bacula}. +\item vous d\'eplacer dans le r\'epertoire obtenu: cd bacula/depkgs +\item ex\'ecuter make + \end{enumerate} + +La composition exacte des paquetages de d\'ependance est susceptible de +changer de temps en temps, voici sa composition actuelle : + +\begin{longtable}{|l|l|l|} + \hline +\multicolumn{1}{|c| }{\bf Paquets externes } & \multicolumn{1}{c| }{\bf depkgs +} & \multicolumn{1}{c| }{\bf depkgs1 } \\ + \hline +{SQLite } & \multicolumn{1}{c| }{X } & \multicolumn{1}{c| }{- } \\ + \hline +{SQLite3 } & \multicolumn{1}{c| }{X } & \multicolumn{1}{c| }{- } \\ + \hline +{mtx } & \multicolumn{1}{c| }{X } & \multicolumn{1}{c| }{- } \\ + \hline +{readline } & \multicolumn{1}{c| }{- } & \multicolumn{1}{c| }{X } \\ + \hline +{pthreads } & \multicolumn{1}{c| }{- } & \multicolumn{1}{c| }{- } \\ + \hline +{zlib } & \multicolumn{1}{c| }{- } & \multicolumn{1}{c| }{- } \\ + \hline +{wxWidgets } & \multicolumn{1}{c| }{- } & \multicolumn{1}{c| }{- } \\ +\hline + +\end{longtable} + +Notez que certains de ces paquets sont de taille respectable, si bien que +l'\'etape de compilation peut prendre un certain temps. Les instructions +ci-dessous construiront tous les paquets contenus dans le r\'epertoire. +Cependant, la compilation de Bacula, ne prendra que les morceaux dont Bacula a +effectivement besoin. + +Une alternative consiste \`a ne construire que les paquets n\'ecessaires. Par +exemple, + +\footnotesize +\begin{verbatim} +cd bacula/depkgs +make sqlite +\end{verbatim} +\normalsize + +configurera et construira SQLite et seulement SQLite. + +Vous devriez construire les paquets requis parmi {\bf depkgs} et/ou {\bf +depkgs1} avant de configurer et compiler Bacula car Bacula en aura besoin +d\`es la compilation. + +M\^eme si vous n'utilisez pas SQLite, vous pourriez trouver le paquet {\bf +depkgs} pratique pour construire {\bf mtx} car le programme {\bf tapeinfo} qui +vient avec peut souvent vous fournir de pr\'ecieuses informations sur vos +lecteurs de bandes SCSI (e.g. compression, taille min/max des blocks,...). + +Le paquet {\bf depkgs-win32} est obsolète à partir de la version 1.39 de Bacula. +Il était autrefois utilisé pour compiler le client natif Win32 qui est +désormais construit sur Linux grâce à un mécanisme de compilation croisée. +Tous les outils et librairies tierces sont automatiquement téléchargées +par l'exécution de scripts apropriés. Lisez le fichier src/win32/README.mingw32 +pour plus de détails. + +\section{Syst\`emes Support\'es} +\label{Systems} +\index[general]{Syst\`emes Support\'es } +\addcontentsline{toc}{section}{Syst\`emes Support\'es} + +Veuillez consulter la section +\ilink{ Syst\`emes support\'es}{SupportedOSes} du chapitre +D\'emarrer avec Bacula de ce manuel. + +\section{Construire Bacula \`a partir des sources} +\label{Building} +\index[general]{Construire Bacula \`a partir des sources } +\index[general]{Sources!Construire Bacula \`a partir des } +\addcontentsline{toc}{section}{Construire Bacula \`a partir des sources} + +L'installation basique est plut\^ot simple. + +\begin{enumerate} +\item Installez et construisez chaque {\bf depkgs} comme indiqu\'e plus haut. + + +\item Configurez et installez MySQL ou PostgreSQL (si vous le souhaitez): + \ilink{Installer et configurer MySQL Phase I}{_ChapterStart} ou + \ilink{Installer et configurer PostgreSQL Phase +I}{_ChapterStart10}. Si vous installez depuis des rpms, et +utilisez MySQL, veillez \`a installer {\bf mysql-devel}, afin que les +fichiers d'en-t\^etes de MySQL soient disponibles pour la compilation de +Bacula. De plus, la librairie client MySQL requi\`ert la librairie de +compression gzip {\bf libz.a} ou {\bf libz.so}. Ces librairies sont dans le +paquet {\bf libz-devel}. Sur Debian, vous devrez charger le paquet {\bf +zlib1g-dev}. Si vous n'utilisez ni rpms, ni debs, il vous faudra trouver le +paquetage adapt\'e \`a votre syst\`eme. + +Notez que si vous avez dej\`a MySQL +ou PostgreSQL sur votre syst\`eme vous pouvez sauter cette phase pourvu que +vous ayez construit "the thread safe libraries'' et que vous ayez d\'ej\`a +install\'e les rpms additionnels sus-mentionn\'es. + +\item En alternative \`a MySQL et PostgreSQL, configurez et installez SQLite, + qui fait partie du paquetage {\bf depkgs}. + \ilink{Installer et configurer SQLite}{_ChapterStart33}. + SQLite n'est probablement pas adapt\'e \`a un environnement de production + de taille respectable, en raison de sa lenteur par rapport \`a MySQL, et de la + pauvret\'e de ses outils de reconstruction de base de donn\'ees endommag\'ee. + +\item D\'esarchivez les sources de Bacula, de pr\'ef\'erence dans le + r\'epertoire {\bf bacula} \'evoqu\'e ci-dessus. + +\item D\'eplacez-vous dans ce r\'epertoire. + +\item Ex\'ecutez ./configure (avec les options appropri\'ees comme d\'ecrit + ci-dessus) + +\item Examinez tr\`es attentivement la sortie de ./configure, + particuli\`erement les r\'epertoires d'installation des binaires et des + fichiers de configuration. La sortie de ./configure est stock\'ee dans le +fichier {\bf config.out} et peut \^etre affich\'ee \`a volont\'e sans +relancer ./configure par la commande {\bf cat config.out}. + +\item Vous pouvez relancer ./configure avec des options diff\'erentes apr\`es + une premi\`ere ex\'ecution, cela ne pose aucun probl\`eme, mais vous devriez + d'abord ex\'ecuter: + +\footnotesize +\begin{verbatim} + make distclean +\end{verbatim} +\normalsize + +afin d'\^etre certain de repartir de z\'ero et d'\'eviter d'avoir un m\'elange +avec vos premi\`eres options. C'est n\'ecessaire parce que ./configure met +en cache une bonne partie des informations. {\bf make distclean} est aussi +recommand\'e si vous d\'eplacez vos fichiers source d'une machine \`a une +autre. Si {\bf make distclean} \'echoue, ignorez-le et continuez. + +\item make + + Si vous obtenez des erreurs durant le {\it linking} dans le r\'epertoire du +Storage Daemon (/etc/stored), c'est probablement parce que vous avez charg\'e +la librairie statique sur votre syst\`eme. J'ai remarqu\'e ce probl\`eme sur +un Solaris. Pour le corriger, assurez-vous de ne pas avoir ajout\'e l'option +{\bf \verb{--{enable-static-tools} \`a la commande {\bf ./configure}. + +Si vous ignorez cette \'etape ({\bf make}) et poursuivez imm\'ediatement avec +{\bf make install}, vous commettez deux erreurs s\'erieuses : d'abord, votre +installation va \'echouer car Bacula a besoin d'un {\bf make} avant un +{\bf make install} ; ensuite, vous vous privez de la possibilit\'e de vous +assurer qu'il n'y a aucune erreur avant de commencer \`a \'ecrire les fichiers dans +vos r\'epertoires syst\`eme. + +\item make install +Avant de lancer cette commande, v\'erifiez consciencieusement que vous avez bien +ex\'ecut\'e la commande {\bf make} et que tout a \'et\'e compil\'e proprement et li\'e +sans erreur. + +\item Si vous \^etes un nouvel utilisateur de Bacula, nous vous recommandons + {\bf fortement} de sauter l'\'etape suivante et d'utiliser le fichier de + configuration par d\'efaut, puis d'ex\'ecuter le jeu d'exemples du prochain +chapitre avant de revenir modifier vos fichier de configuration pour qu'ils +satisfassent vos besoins. + +\item Modifiez les fichiers de configuration de chacun des trois {\it daemons} + (Directory, File, Storage) et celui de la Console. Pour plus de d\'etails, + consultez le chapitre +\ilink{Fichiers de Configuration de Bacula}{_ChapterStart16} Nous +vous recommandons de commencer par modifier les fichiers de configuration +fournis par d\'efaut, en faisant les changements minima indispensables. Vous +pourrez proc\'eder \`a une adaptation compl\`ete une fois que Bacula +fonctionnera correctement. Veuillez prendre garde \`a modifier les mots de +passe qui sont g\'en\'er\'es al\'eatoirement, ainsi que les noms car ils +doivent s'accorder entre les fichiers de configuration pour des raisons de +s\'ecurit\'e. + +\item Cr\'eez la base de donn\'ees Bacula MySQL et ses tables (si vous + utilisez MySQL) + \ilink{Installer et configurer MySQL Phase II}{mysql_phase2} ou +cr\'eez la base de donn\'ees Bacula PostgreSQL et ses tables +\ilink{Installer et configurer PostgreSQL Phase +II}{PostgreSQL_phase2} (si vous utilisez PostgreSQL) ou +encore +\ilink{Installer et configurer SQLite Phase II}{phase2} (si vous +utilisez SQLite) + +\item D\'emarrez Bacula ({\bf ./bacula start}) Notez: Le prochain chapitre + expose ces \'etapes en d\'etail. + +\item Lancez la Console pour communiquer avec Bacula. + +\item Pour les deux \'el\'ements pr\'ec\'edents, veuillez suivre les + instructions du chapitre + \ilink{Ex\'ecuter Bacula}{_ChapterStart1} o\`u vous ferez une +simple sauvegarde et une restauration. Faites ceci avant de faire de lourdes +modifications aux fichiers de configuration, ainsi vous serez certain que +Bacula fonctionne, et il vous sera plus familier. Apr\`es quoi il vous sera +plus facile de changer les fichiers de configuration. +\item Si apr\`es l'installation de Bacula, vous d\'ecidez de le d\'eplacer, + c'est \`a dire de l'installer dans un jeu de r\'epertoires diff\'erents, + proc\'edez comme suit : + +\footnotesize +\begin{verbatim} + make uninstall + make distclean + ./configure (vos-nouvelles-options) + make + make install + +\end{verbatim} +\normalsize + +\end{enumerate} + +Si tout se passe bien, {\bf ./configure} d\'eterminera correctement votre +syst\`eme et configurera correctement le code source. Actuellement, FreeBSD, +Linux (RedHat), et Solaris sont support\'es. Des utilisateurs rapportent que +le client Bacula fonctionne sur MacOS X 10.3 tant que le support readline est +d\'esactiv\'e. + +Si vous installez Bacula sur plusieurs syst\`emes identiques, vous pouvez +simplement transf\'erer le r\'epertoire des sources vers ces autres syst\`emes +et faire un "make install''. Cependant s'il y a des diff\'erences dans les +librairies, ou les versions de syst\`emes, ou si vous voulez installer sur un +syst\`eme diff\'erent, vous devriez recommencer \`a partir de l'archive tar +compress\'ee originale. Si vous transf\'erez un r\'epertoire de sources o\`u +vous avez d\'ej\`a ex\'ecut\'e la commande ./configure, vous DEVEZ faire: + +\footnotesize +\begin{verbatim} +make distclean +\end{verbatim} +\normalsize + +avant d'ex\'ecuter \`a nouveau ./configure. Ceci est rendu n\'ecessaire par +l'outil GNU autoconf qui met la configuration en cache, de sorte que si vous +r\'eutilisez la configuration d'une machine Linux sur un Solaris, vous pouvez +\^etre certain que votre compilation \'echouera. Pour l'\'eviter, comme +mentionn\'e plus haut, recommencez depuis l'archive tar, ou faites un "make +distclean''. + +En g\'en\'eral, vous voudrez probablement sophistiquer votre {\bf configure} +pour vous assurer que tous les modules que vous souhaitez soient construits et +que tout soit plac\'e dans les bons r\'epertoires. + +Par exemple, sur Fedora, RedHat ou SuSE, on pourrait utiliser ceci: + +\footnotesize +\begin{verbatim} +CFLAGS="-g -Wall" \ + ./configure \ + --sbindir=$HOME/bacula/bin \ + --sysconfdir=$HOME/bacula/bin \ + --with-pid-dir=$HOME/bacula/bin/working \ + --with-subsys-dir=$HOME/bacula/bin/working \ + --with-mysql \ + --with-working-dir=$HOME/bacula/bin/working \ + --with-dump-email=$USER +\end{verbatim} +\normalsize + +Notez: l'avantage de cette configuration pour commencer, est que tout sera mis +dans un seul r\'epertoire, que vous pourrez ensuite supprimer une fois que +vous aurez ex\'ecut\'e les exemples du prochain chapitre, et appris comment +fonctionne Bacula. De plus, ceci peut \^etre install\'e et ex\'ecut\'e sans +\^etre root. + +Pour le confort des d\'eveloppeurs, j'ai ajout\'e un script {\bf +defaultconfig} au r\'epertoire {\bf examples}. Il contient les r\'eglages que +vous devriez normalement utiliser, et chaque d\'eveloppeur/utilisateur devrait +le modifier pour l'accorder \`a ses besoins. Vous trouverez d'autres exemples +dans ce r\'epertoire. + +Les options {\bf \verb{--{enable-conio} ou {\bf \verb{--{enable-readline} sont utiles car +elles conf\`erent un historique de lignes de commandes et des capacit\'es +d'\'edition \`a la Console. Si vous avez inclus l'une ou l'autre option, l'un +des deux paquets {\bf termcap} ou {\bf ncurses} sera n\'ecessaire pour +compiler. Sur la plupart des syst\`emes, y compris RedHat et SuSE, vous +devriez inclure le paquet ncurses. Si Le processus de configuration de +Bacula le d\'etecte, il l'utilisera plut\^ot que la librairie termcap. +Sur certains syst\`emes, tels que SUSE, la librairie termcap n'est +pas dans le r\'epertoire standard des librairies par cons\'equent, l'option +devrait \^etre d\'esactiv\'ee ou vous aurez un message tel que: + +\footnotesize +\begin{verbatim} +/usr/lib/gcc-lib/i586-suse-linux/3.3.1/.../ld: +cannot find -ltermcap +collect2: ld returned 1 exit status +\end{verbatim} +\normalsize + +lors de la compilation de la Console Bacula. Dans ce cas, il vous faudra +placer la variable d'environnement {\bf LDFLAGS} avant de compiler. + +\footnotesize +\begin{verbatim} +export LDFLAGS="-L/usr/lib/termcap" +\end{verbatim} +\normalsize + +Les m\^emes contraintes de librairies s'appliquent si vous souhaitez utiliser +les sous-programmes readlines pour l'\'edition des lignes de commande et +l'historique, ou si vous utilisez une librairie MySQL qui requiert le +chiffrement. Dans ce dernier cas, vous pouvez exporter les librairies +additionnelles comme indiqu\'e ci-dessus ou, alternativement, les inclure +directement en param\`etres de la commande ./configure comme ci-dessous : + + \footnotesize + \begin{verbatim} + LDFLAGS="-lssl -lcyrpto" \ + ./configure + \end{verbatim} +\normalsize + + +Veuillez noter que sur certains syst\`emes tels que Mandriva, readline tend +\`a "avaler'' l'invite de commandes, ce qui le rend totalement inutile. Si +cela vous arrive, utilisez l'option "disable'', ou si vous utilisez une +version post\'erieure \`a 1.33 essayez {\bf \verb{--{enable-conio} pour utiliser une +alternative \`a readline int\'egr\'ee. Il vous faudra tout de m\^eme termcap +ou ncurses, mais il est peu probable que le paquetage {\bf conio} gobe vos +invites de commandes. + +Readline n'est plus support\'e depuis la version 1.34. Le code reste +disponible, et si des utilisateurs soumettent des patches, je serai heureux de +les appliquer. Cependant, \'etant donn\'e que chaque version de readline +semble incompatible avec les pr\'ec\'edentes, et qu'il y a des diff\'erences +significatives entre les syst\`emes, je ne puis plus me permettre de le +supporter. + +\section{Quelle base de donn\'ees utiliser ?} +\label{DB} +\index[general]{Utiliser!Quelle base de donn\'ees } +\index[general]{Quelle base de donn\'ees utiliser ? } +\addcontentsline{toc}{section}{Quelle base de donn\'ees utiliser ?} + +Avant de construire Bacula, vous devez d\'ecider si vous voulez utiliser +SQLite, MySQL ou PostgreSQL. Si vous n'avez pas d\'ej\`a MySQL ou PostgreSQL +sur votre machine, nous vous recommandons de d\'emarrer avec SQLite. Ceci vous +facilitera beaucoup l'installation car SQLite est compil\'e dans Bacula et ne +requiert aucune administration. SQLite fonctionne bien et sied bien aux +petites et moyennes configurations (maximum 10-20 machines). Cependant, il nous +faut signaler que plusieurs utilisateurs ont subi des corruptions inexpliqu\'ees +de leur catalogue SQLite. C'est pourquoi nous recommandons de choisir MySQL +ou PostgreSQL pour une utilisation en production. + +Si vous souhaitez utiliser MySQL pour votre catalogue Bacula, consultez le +chapitre +\ilink{Installer et Configurer MySQL}{_ChapterStart} de ce manuel. +Vous devrez installer MySQL avant de poursuivre avec la configuration de +Bacula. MySQL est une base de donn\'ees de haute qualit\'e tr\`es efficace et +qui convient pour des configurations de toutes tailles. MySQL est +l\'eg\`erement plus complexe \`a installer et administrer que SQLite en raison +de ses nombreuses fonctions sophistiqu\'ees telles que userids et mots de +passe. MySQL fonctionne en tant que processus distinct, est r\'eellement une +solution professionnelle et peut prendre en charge des bases de donn\'ees de +dimension quelconque. + +Si vous souhaitez utiliser PostgreSQL pour votre catalogue Bacula, consultez +le chapitre +\ilink{Installer et Configurer PostgreSQL}{_ChapterStart10} de ce +manuel. Vous devrez installer PostgreSQL avant de poursuivre avec la +configuration de Bacula. PostgreSQL est tr\`es similaire \`a MySQL bien que +tendant \`a \^etre un peu plus conforme \`a SQL92. PostgreSQL poss\`ede +beaucoup plus de fonctions avanc\'ees telles que les transactions, les +proc\'edures stock\'ees, etc. PostgreSQL requiert une certaine connaissance +pour son installation et sa maintenance. + +Si vous souhaitez utiliser SQLite pour votre catalogue Bacula, consultez le +chapitre +\ilink{Installer et Configurer SQLite}{_ChapterStart33} de ce manuel. + +\section{D\'emarrage rapide} +\index[general]{D\'emarrage rapide } +\index[general]{Rapide!D\'emarrage } +\addcontentsline{toc}{section}{D\'emarrage rapide} + +Il y a de nombreuses options et d'importantes consid\'erations donn\'ees +ci-dessous que vous pouvez passer pour le moment si vous n'avez eu aucun +probl\`eme lors de la compilation de Bacula avec une configuration +simplifi\'ee comme celles montr\'ees plus haut. + +Si le processus ./configure ne parvient pas \`a trouver les librairies +sp\'ecifiques (par exemple libintl), assurez vous que le paquetage appropri\'e +est install\'e sur votre syst\`eme. S'il est install\'e dans un r\'epertoire non +standard (au moins pour Bacula), il existe dans la plupart des cas une +option parmi celles \'enum\'er\'ees ci-dessous (ou avec "./configure {-}{-}help") +qui vous permettra de sp\'ecifier un r\'epertoire de recherche. D'autres options +vous permettent de d\'esactiver certaines fonctionnalit\'es (par exemple +{-}{-}disable-nls). + +Si vous souhaitez vous jeter \`a l'eau, nous vous conseillons de passer +directement au chapitre suivant, et d'ex\'ecuter le jeu d'exemples. Il vous +apprendra beaucoup sur Bacula, et un Bacula de test peut \^etre install\'e +dans un unique r\'epertoire (pour une destruction ais\'ee) et ex\'ecut\'e sans +\^etre root. Revenez lire les d\'etails de ce chapitre si vous avez un +quelconque probl\`eme avec les exemples, ou lorsque vous voudrez effectuer une +installation r\'eelle. + +TAQUET MISE A JOUR + +\section{Options de la commande {\bf configure}} +\label{Options} +\index[general]{Options de la commande configure } +\index[general]{Configure!Options de la commande } +\addcontentsline{toc}{section}{Options de la commande configure} + +Les options en ligne de commande suivantes sont disponibles pour {\bf +configure} afin d'adapter votre installation \`a vos besoins. + +\begin{description} + +\item [{-}{-}sysbindir=\lt{}binary-path\gt{}] + \index[dir]{{-}{-}sysbindir } + D\'efinit l'emplacement des binaires Bacula. + +\item [{-}{-}sysconfdir=\lt{}config-path\gt{}] + \index[dir]{{-}{-}sysconfdir } + D\'efinit l'emplacement des fichiers de configuration de Bacula. + +\item [ {-}{-}mandir=\lt{}path\gt{}] + \index[general]{{-}{-}mandir} + Notez qu'\`a partir de la version 1.39.14, tout chemin sp\'ecifi\'e + est d\'esormais compris comme le niveau le plus \'elev\'e du + r\'epertoire man. Pr\'ec\'edemment, le {\bf mandir} sp\'ecifiait le + chemin absolu o\`u vous souhaitiez instaler les pages de manuel. + Les fichiers man sont install\'es au format gzipp\'e sous + mandir/man1 et mandir/man8 comme il convient. + Pour que l'installation se d\'eroule normalement, vous devez + disposer de {\bf gzip} sur votre syst\`eme + + Par d\'efaut, Bacula installe une simple page de manuel dans + /usr/share/man. Si vous voulez qu'elle soit install\'ee ailleurs, + utilisez cette options pour sp\'ecifier le chemin voulu. Notez + que les principaux documents Bacula en HTML et PDF sont dans une + archive tar distincte des sources de distribution de Bacula. + +\item [ {-}{-}datadir=\lt{}path\gt{}] + \index[general]{{-}{-}datadir} + Si vous traduisez Bacula ou des parties de Bacula dans une autre + langue, vous pouvez sp\'ecifier l'emplacement des fichiers .po avec + l'option {\bf {-}{-}datadir}. Vous devez installer manuellement tout + fichier .po qui n'est pas (encore) install\'e automatiquement. + +\item [{-}{-}enable-smartalloc ] + \index[dir]{{-}{-}enable-smartalloc } + Permet l'inclusion du code Smartalloc de d\'etection de tampons orphelins +(NDT : orphaned buffer). Cette option est vivement recommand\'ee. Nous n'avons +jamais compil\'e sans elle, aussi vous pourriez subir des d\'esagr\'ements si +vous ne l'activez pas. Dans ce cas, r\'eactivez simplement cette option. Nous +la recommandons car elle aide \`a d\'etecter les fuites de m\'emoire. Ce +param\`etre est utilis\'e lors de la compilation de Bacula. + +\item [{-}{-}enable-gnome ] + \index[dir]{{-}{-}enable-gnome } + Si vous avez install\'e GNOME sur votre ordinateur, vous devez sp\'ecifier +cette option pour utiliser la Console graphique GNOME. Vous trouverez les +binaires dans le r\'epertoire {\bf src/gnome-console}. + +\item [{-}{-}enable-bwx-console ] + \index[general]{{-}{-}enable-bwx-console } + Si vous avez install\'e wxWidgets sur votre ordinateur, vous devez +sp\'ecifier cette option pour utiliser la Console graphique bwx-console. Vous +trouverez les binaires dans le r\'epertoire {\bf src/wx-console}. Ceci peut +\^etre utile aux utilisateurs qui veulent une Console graphique, mais ne +souhaitent pas installer Gnome, car wxWidgets peut fonctionner avec les +librairies GTK+, Motif ou m\^eme X11. + +\item [{-}{-}enable-tray-monitor ] + \index[general]{{-}{-}enable-tray-monitor } + Si vous avez install\'e GTK sur votre ordinateur et utilisez un gestionnaire +de fen\^etre compatible avec le syst\`eme de notification standard FreeDesktop +(tels KDE et GNOME), vous pouvez utiliser une interface graphique pour +surveiller les {\it daemons} Bacula en activant cette option. Les binaires +seront plac\'es dans le r\'epertoire {\bf src/tray-monitor}. + +\item [{-}{-}enable-static-tools] + \index[general]{{-}{-}enable-static-tools } + Avec cette option, les utilitaires relatifs au Storage Daemon ({\bf bls}, +{\bf bextract}, et {\bf bscan}) seront li\'es statiquement, ce qui vous permet +de les utiliser m\^eme si les librairies partag\'ees ne sont pas charg\'ees. +Si vous avez des difficult\'es de type "linking'' \`a la compilation du +r\'epertoire {\bf src/stored}, assurez-vous d'avoir d\'esactiv\'e cette +option, en ajoutant \'eventuellement {\bf \verb{--{disable-static-tools}. + +\item [{-}{-}enable-static-fd] + \index[fd]{{-}{-}enable-static-fd } + Avec cette option, la compilation produira un {\bf static-bacula-fd} en plus +du File Daemon standard. Cette version qui inclut les librairies statiquement +li\'ees est requise pour la reconstruction compl\`ete d'une machine apr\`es +un d\'esastre. Cette option est largement surpass\'ee par l'usage de {\bf +make static-bacula-fd} du r\'epertoire {\bf src/filed}. L'option {\bf +\verb:--:enable-client-only} d\'ecrite plus loin est aussi int\'eressante +pour compiler un simple client sans les autres parties du programme. + +Pour lier un binaire statique, l'\'editeur de liens a besoin des versions +statiques de toutes les librairies utilis\'ees, aussi les utilisateurs +rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation +de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la +librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut +s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou +{\bf {-}{-}with-python} de la commande configure, car elle requierent des +librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais +il vous faudra charger les librairies statiques additionnelles correspondantes. + +\item [{-}{-}enable-static-sd] + \index[sd]{{-}{-}enable-static-sd } + Avec cette option, la compilation produira un {\bf static-bacula-sd} en plus +du Storage Daemon standard. Cette version qui inclut les librairies +statiquement li\'ees peut se r\'ev\'eler utile pour la reconstruction +compl\`ete d'une machine apr\`es un d\'esastre. + +Pour lier un binaire statique, l'\'editeur de liens a besoin des versions +statiques de toutes les librairies utilis\'ees, aussi les utilisateurs +rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation +de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la +librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut +s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou +{\bf {-}{-}with-python} de la commande configure, car elle requierent des +librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais +il vous faudra charger les librairies statiques additionnelles correspondantes. + +\item [{-}{-}enable-static-dir] + \index[dir]{{-}{-}enable-static-dir } + Avec cette option, la compilation produira un {\bf static-bacula-dir} en plus +du Director Daemon standard. Cette version qui inclut les librairies +statiquement li\'ees peut se r\'ev\'eler utile pour la reconstruction +compl\`ete d'une machine apr\`es un d\'esastre. + +Pour lier un binaire statique, l'\'editeur de liens a besoin des versions +statiques de toutes les librairies utilis\'ees, aussi les utilisateurs +rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation +de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la +librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut +s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou +{\bf {-}{-}with-python} de la commande configure, car elle requierent des +librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais +il vous faudra charger les librairies statiques additionnelles correspondantes. + +\item [{-}{-}enable-static-cons] + \index[dir]{{-}{-}enable-static-cons } + Avec cette option, la compilation produira une {\bf static-console} et une +{\bf static-gnome-console} en plus de la Console standard standard. Cette +version qui inclut les librairies statiquement li\'ees peut se r\'ev\'eler +utile pour la reconstruction compl\`ete d'une machine apr\`es un d\'esastre. + +Pour lier un binaire statique, l'\'editeur de liens a besoin des versions +statiques de toutes les librairies utilis\'ees, aussi les utilisateurs +rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation +de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la +librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut +s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou +{\bf {-}{-}with-python} de la commande configure, car elle requierent des +librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais +il vous faudra charger les librairies statiques additionnelles correspondantes. + +\item [{-}{-}enable-client-only] + \index[general]{{-}{-}enable-client-only } + Avec cette option, la compilation produira seulement le File Daemon et les +librairies qui lui sont n\'ecessaires. Aucun des autres {\it daemons}, outils +de stockage, ni la console ne sera compil\'e. De m\^eme, un {\bf make +install} installera seulement le File Daemon. Pour obtenir tous les {\it +daemons}, vous devez la d\'esactiver. Cette option facilite grandement la +compilation sur les simples clients. + +Pour lier un binaire statique, l'\'editeur de liens a besoin des versions +statiques de toutes les librairies utilis\'ees, aussi les utilisateurs +rencontrent fr\'equemment des erreurs d'\'edition de liens \`a l'utilisation +de cette option. La premi\`ere chose \`a faire est de s'assurer d'avoir la +librairie glibc statiquement li\'ee sur votre syst\`eme. Ensuite, il faut +s'assurer de ne pas utiliser les options {\bf {-}{-}openssl} ou +{\bf {-}{-}with-python} de la commande configure, car elle requierent des +librairies suppl\'ementaires. Vous devriez pouvoir activer ces options, mais +il vous faudra charger les librairies statiques additionnelles correspondantes. + +\item [ {-}{-}enable-build-dird] + \index[general]{{-}{-}enable-build-dird} +Avec cette option activ\'ee (ce qui est le cas par d\'efaut), le processus make +compile le Director ainsi que les outils du Director. Vous pouvez d\'esactiver +la compilation du Director en utilisant {\bf {-}{-}disable-build-dird}. + +\item [ {-}{-}enable-build-stored] + \index[general]{{-}{-}enable-build-stored} +Avec cette option activ\'ee (ce qui est le cas par d\'efaut), le processus make +compile le Storage Daemon. Vous pouvez d\'esactiver +la compilation du Storage Daemon en utilisant {\bf {-}{-}disable-build-stored}. + +\item [{-}{-}enable-largefile] + \index[general]{{-}{-}enable-largefile } + Cette option (activ\'ee par d\'efaut) provoque la compilation de Bacula avec +le support d'adressage de fichiers 64 bits s'il est disponible sur votre +syst\`eme. Ainsi Bacula peut lire et \'ecrire des fichiers de plus de 2 +GBytes. Vous pouvez d\'esactiver cette option et revenir \`a un adressage de +fichiers 32 bits en utilisant {\bf \verb{--{disable-largefile}. + +\item [ {-}{-}disable-nls] + \index[general]{{-}{-}disable-nls} + Bacula utilise par d\'efaut les librairies {\it GNU Native Language Support} (NLS). + Sur certaines machines, ces librairies peuvent \^etre inexistante, ou ne pas + fonctionner correctement (particuli\`erement sur les impl\'ementations non Linux). + dans ce genre de situations, vous pouvez neutraliser l'utilisation de ces librairies + avec l'option {\bf {-}{-}disable-nls}. Dans ce cas, Bacula reviendra \`a l'usage de l'anglais. + +\item [{-}{-}with-sqlite=\lt{}sqlite-path\gt{}] + \index[general]{{-}{-}with-sqlite } + Cette option permet l'utilisation de la base de donn\'ees SQLite versions 2.8.x. Il n'est, +en principe, pas n\'ecessaire de sp\'ecifier le chemin {\bf sqlite-path} car +Bacula recherche les composants requis dans les r\'epertoires standards ({\bf +depkgs/sqlite}). voyez +\ilink{Installer et Configurer SQLite}{_ChapterStart33} pour plus de +d\'etails. + +Voyez aussi la note ci-dessous, apr\`es le paragraphe --with-postgreSQL + +\item [{-}{-}with-sqlite3=\lt{}sqlite3-path\gt{}] + \index[general]{{-}{-}with-sqlite3 } + Cette option permet l'utilisation de la base de donn\'ees SQLite versions 3.x. Il n'est, +en principe, pas n\'ecessaire de sp\'ecifier le chemin {\bf sqlite3-path} car +Bacula recherche les composants requis dans les r\'epertoires standards ({\bf +depkgs/sqlite3}). voyez +\ilink{Installer et Configurer SQLite}{_ChapterStart33} pour plus de +d\'etails. + +Voyez aussi la note ci-dessous, apr\`es le paragraphe --with-postgreSQL + +\item [{-}{-}with-mysql=\lt{}mysql-path\gt{}] + \index[general]{{-}{-}with-mysql } + Cette option permet la compilation des services de Catalogue de Bacula. Elle +implique que MySQL tourne d\'ej\`a sur votre syst\`eme, et qu'il soit +install\'e dans le chemin {\bf mysql-path} que vous avez sp\'ecifi\'e. Si +cette option est absente, Bacula sera compil\'e automatiquement avec le code +de la base Bacula interne. Nous recommandons d'utiliser cette option si +possible. Si vous souhaitez utilisez cette option, veuillez proc\'eder \`a +l'installation de MySQL ( +\ilink{Installer and Configurer MySQL}{_ChapterStart}) avant de +proc\'eder \`a la configuration. + +Voyez aussi la note ci-dessous, apr\`es le paragraphe --with-postgreSQL + +\item [{-}{-}with-postgresql=\lt{}postgresql-path\gt{}] + \index[general]{{-}{-}with-postgresql } + Cette option d\'eclare un chemin explicite pour les librairies PostgreSQL si +Bacula ne les trouve pas dans le r\'epertoire par d\'efaut. + +Notez que pour que Bacula soit configur\'e correctement, vous devez sp\'ecifier l'une des +quatre options de bases de donn\'ees support\'ees : {-}{-}with-sqlite, {-}{-}with-sqlite3, +{-}{-}with-mysql, ou {-}{-}with-postgresql, faute de quoi ./configure \'echouera. + +\item [ {-}{-}with-openssl=\lt{}path\gt{}] + Cette option est requise si vous souhaitez activer TLS (ssl) qui chiffre les + communications entre les daemons Bacula ou si vous voulez utiliser le chiffrement + PKI des données du File Daemon.Normalement, la sp\'ecification du chemin {\bf path} + n'est pas n\'ecessaire car le processus de + configuration recherche les librairies OpenSSL dans les emplacements standard du + syst\`eme. L'activation d'OpenSSL dans Bacula permet des communications s\'ecuris\'ees + entre les {\it daemons}. Pour plus d'informations sur l'usage de TLS, consultez le + chapitre \ilink{Bacula TLS}{_ChapterStart61} de ce manuel. Pour plus d'informations + sur l'usage du chiffrement des données PKI, veuillez consulter le chapitre + \ilink{Bacula PKI -- Data Encryption}{Chiffrement des données} de ce manuel. + +\item [ {-}{-}with-python=\lt{}path\gt{}] + \index[general]{{-}{-}with-python } + Cette option active le support Python dans Bacula. Si le chemin n'est pas + sp\'ecifi\'e, le processus de configuration recherchera les librairies Python + dans leurs emplacements standard. S'il ne peut trouver les librairies , il vous faudra + fournir le chemin vers votre r\'epertoire de librairies Python. Voyez le + \ilink{chapitre Python}{_ChapterStart60} pour plus de d\'etails sur l'utilisation de + scripts Python. + +\item [ {-}{-}with-libintl-prefix=\lt{}DIR\gt{}] + \index[general]{{-}{-}with-libintl-prefix} + Cette option peut \^etre utilis\'ee pour indiquer \`a Bacula de rechercher dans DIR/include + et DIR/lib les fichiers d'en t\^ete libintl et les librairies requises pour + Native Language Support (NLS). + +\item [{-}{-}enable-conio] + \index[general]{{-}{-}enable-conio } + Cette option permet la compilation d'une petite et l\'eg\`ere routine en +alternative \`a readline, beaucoup plus facile \`a configurer, m\^eme si elle +n\'ecessite aussi les librairies termcap ou ncurses. + +\item [{-}{-}with-readline=\lt{}readline-path\gt{}] + \index[general]{{-}{-}with-readline } + Sp\'ecifie l'emplacement de {\bf readline}. En principe, Bacula devrait le +trouver s'il est dans une librairie standard. Sinon, et si l'option +\verb{--{with-readline n'est pas renseign\'ee, readline sera d\'esactiv\'e. Cette +option affecte la compilation de Bacula. Readline fournit le programme +Console avec un historique des lignes de commandes et des capacit\'es +d'\'edition. Readline n'est d\'esormais plus support\'e, ce qui signifie que +vous l'utilisez \`a vos risques et p\'erils + +\item [{-}{-}enable-readline] + \index[general]{{-}{-}enable-readline } + Active le support readline. D\'esactiv\'e par d\'efaut en raison de nombreux +probl\`emes de configuration, et parce que le paquetage semble devenir +incompatible. + +\item [{-}{-}with-tcp-wrappers=\lt{}path\gt{}] + \index[general]{{-}{-}with-tcp-wrappers} + \index[general]{TCP Wrappers} + \index[general]{Wrappers!TCP} + \index[general]{libwrappers} + Cette option pr\'ecise que vous voulez TCP wrappers (man hosts\_access(5)) +compil\'e dans Bacula. Le chemin est facultatif puisque Bacula devrait, en +principe, trouver les librairies dans les r\'epertoires standards. Cette +option affecte la compilation. Lorsque vous sp\'ecifierez vos restrictions +dans les fichiers {\bf /etc/hosts.allow} ou {\bf /etc/hosts.deny}, n'utilisez +pas l'option {\bf twist} (man hosts\_options(5)) ou le processus Bacula sera +stopp\'e. + +Pour plus d'informations sur la configuration et les tests de TCP wrappers, +consultez la section +\ilink{Configurer et Tester TCP Wrappers}{wrappers} du chapitre +sur la s\'ecurit\'e. + +Sur SuSE, les librairies libwrappers requises pour lier Bacula appartiennent +au paquet tcpd-devel. Sur RedHat, le paquet se nomme tcp\_wrappers. + +\item [{-}{-}with-working-dir=\lt{}working-directory-path\gt{}] + \index[dir]{{-}{-}with-working-dir } + Cette option est obligatoire et sp\'ecifie un r\'epertoire dans lequel Bacula +peut placer en toute s\'ecurit\'e les fichiers qui resteront d'une +ex\'ecution \`a l'autre. Par exemple, si la base de donn\'ees interne est +utilis\'ee, Bacula stockera ces fichiers dans ce r\'epertoire. Cette option +n'est utilis\'ee que pour modifier les fichiers de configuration de Bacula. +Vous pourrez \'eventuellement effectuer cette modification directement en les +\'editant plus tard. Le r\'epertoire sp\'ecifi\'e ici n'est pas +automatiquement cr\'e\'e par le processus d'installation, aussi vous devez +veiller \`a ce qu'il existe avant votre premi\`ere utilisation de Bacula. + +\item [{-}{-}with-base-port=\lt{}port=number\gt{}] + \index[dir]{{-}{-}with-base-port } + Bacula a besoin de trois ports TCP/IP pour fonctionner (un pour la Console, +un pour le Storage Daemon et un pour le File Daemon). L'option {\bf +\verb{--{with-baseport} permet d'assigner automatiquement trois ports cons\'ecutifs +\`a partir du port de base sp\'ecifi\'e. Vous pouvez aussi changer les +num\'eros de ports dans les fichiers de configuration. Cependant, vous devez +prendre garde \`a ce que les num\'eros de ports se correspondent fid\`element +dans chacun des trois fichiers de configuration. Le port de base par d\'efaut +est 9101, ce qui assigne les ports 9101 \`a 9103. Ces ports (9101, 9102 et +9103) ont \'et\'e officiellement assign\'e \`a Bacula par l'IANA. Cette +option n'est utilis\'ee que pour modifier les fichiers de configuration de +Bacula. Vous pouvez \`a tout moment faire cette modification en \'editant +directement ces fichiers. + +\item [{-}{-}with-dump-email=\lt{}email-address\gt{}] + \index[dir]{{-}{-}with-dump-email } + Cette option sp\'ecifie l'adresse e-mail qui recevra tous les {\it core dump}. + Cette option n'est en principe utilis\'ee que par les d\'eveloppeurs. + +\item [{-}{-}with-pid-dir=\lt{}PATH\gt{} ] + \index[dir]{{-}{-}with-pid-dir } + Ceci pr\'ecise le r\'epertoire de stockage du fichier d'id de processus lors +de l'ex\'ecution. La valeur par d\'efaut est : {\bf /var/run}. Le r\'epertoire +sp\'ecifi\'e ici n'est pas automatiquement cr\'e\'e par le processus +d'installation, aussi vous devez veiller \`a ce qu'il existe avant votre +premi\`ere utilisation de Bacula. + +\item [{-}{-}with-subsys-dir=\lt{}PATH\gt{} ] + \index[dir]{{-}{-}with-subsys-dir } + Cette option pr\'ecise le r\'epertoire de stockage des fichiers verrous du +sous-syst\`eme lors de l'ex\'ecution. Le r\'epertoire par d\'efaut est {\bf +/var/run/subsys}. Veillez \`a ne pas sp\'ecifier le m\^eme r\'epertoire que +pour l'option {\bf sbindir}. Ce r\'epertoire n'est utilis\'e que par les +scripts de d\'emarrage automatique. Le r\'epertoire sp\'ecifi\'e ici n'est +pas automatiquement cr\'e\'e par le processus d'installation, aussi vous devez +veiller \`a ce qu'il existe avant votre premi\`ere utilisation de Bacula. + +\item [{-}{-}with-dir-password=\lt{}Password\gt{} ] + \index[dir]{{-}{-}with-dir-password } + Cette option vous permet de pr\'eciser le mot de passe d'acc\`es au Director +(contact\'e, en principe, depuis la console). S'il n'est pas pr\'ecis\'e, +configure en cr\'e\'e un al\'eatoirement. + +\item [{-}{-}with-fd-password=\lt{}Password\gt{} ] + \index[fd]{{-}{-}with-fd-password } + Cette option vous permet de pr\'eciser le mot de passe d'acc\`es au File +Daemon (contact\'e, en principe, depuis le Director). S'il n'est pas +pr\'ecis\'e, configure en cr\'e\'e un al\'eatoirement. + +\item [{-}{-}with-sd-password=\lt{}Password\gt{} ] + \index[sd]{{-}{-}with-sd-password } + Cette option vous permet de pr\'eciser le mot de passe d'acc\`es au Storage +Daemon (contact\'e, en principe, depuis le File Daemon). S'il n'est pas +pr\'ecis\'e, configure en cr\'e\'e un al\'eatoirement. + +\item [{-}{-}with-dir-user=\lt{}User\gt{} ] + \index[dir]{{-}{-}with-dir-user } + Cette option vous permet de sp\'ecifier l'UserId utilis\'e pour l'ex\'ecution +du Director. Le Director doit \^etre d\'emarr\'e en tant que root, mais n'a +pas besoin d'\^etre ex\'ecut\'e en tant que root. Apr\`es avoir effectu\'e les +op\'erations d'initialisation pr\'eliminaires, il peut redescendre au niveau +de l'UserId sp\'ecifi\'e dans cette option. Si vous utilisez cette option, vous +devez cr\'eer l'utilisateur User avant d'ex\'ecuter {\bf make install}, car le +r\'epertoire de travail de Bacula appartiendra \`a cet utilisateur. + +\item [{-}{-}with-dir-group=\lt{}Group\gt{} ] + \index[dir]{{-}{-}with-dir-group } + Cette option vous permet de sp\'ecifier le GroupId utilis\'e pour +l'ex\'ecution du Director. Le Director doit \^etre d\'emarr\'e en tant que +root, mais n'a pas besoin d'\^etre ex\'ecut\'e en tant que root. Apr\`es avoir +effectu\'e les op\'erations d'initialisation pr\'eliminaires, il peut +redescendre au niveau du GroupId sp\'ecifi\'e dans cette option. +Si vous utilisez cette option, vous +devez cr\'eer le groupe Group avant d'ex\'ecuter {\bf make install}, car le +r\'epertoire de travail de Bacula appartiendra \`a ce groupe. + +\item [{-}{-}with-sd-user=\lt{}User\gt{} ] + \index[sd]{{-}{-}with-sd-user } + Cette option vous permet de sp\'ecifier l'UserId utilis\'e pour ex\'ecuter le +Storage Daemon. Le Storage Daemon doit \^etre d\'emarr\'e en tant que root, +mais n'a pas besoin d'\^etre ex\'ecut\'e en tant que root. Apr\`es avoir +effectu\'e les op\'erations d'initialisation pr\'eliminaires, il peut +redescendre au niveau de l'UserId sp\'ecifi\'e dans cette option. Si vous +utilisez cette option, veillez \`a ce que le Storage Daemon ait acc\`es \`a +tous les p\'eriph\'eriques de stockage dont il a besoin. + +\item [{-}{-}with-sd-group=\lt{}Group\gt{} ] + \index[sd]{{-}{-}with-sd-group } + Cette option vous permet de sp\'ecifier le GroupId utilis\'e pour ex\'ecuter +le Storage Daemon. Le Storage Daemon doit \^etre d\'emarr\'e en tant que +root, mais n'a pas besoin d'\^etre ex\'ecut\'e en tant que root. Apr\`es avoir +effectu\'e les op\'erations d'initialisation pr\'eliminaires, il peut +redescendre au niveau du GroupId sp\'ecifi\'e dans cette option. + +\item [{-}{-}with-fd-user=\lt{}User\gt{} ] + \index[fd]{{-}{-}with-fd-user } + Cette option vous permet de sp\'ecifier l'UserId utilis\'e pour ex\'ecuter le +File Daemon. Le File Daemon doit \^etre d\'emarr\'e et, dans la plupart des +cas, ex\'ecut\'e en tant que root, de sorte que cette option n'est utilis\'ee +que dans des cas bien particuliers. Malgr\'e tout, apr\`es avoir effectu\'e +les op\'erations d'initialisation pr\'eliminaires, il peut redescendre au +niveau de l'UserId sp\'ecifi\'e dans cette option. + +\item [{-}{-}with-fd-group=\lt{}Group\gt{} ] + \index[fd]{{-}{-}with-fd-group } + Cette option vous permet de sp\'ecifier le GroupId utilis\'e pour ex\'ecuter +le File Daemon. Le File Daemon doit \^etre d\'emarr\'e et, dans la plupart +des cas, ex\'ecut\'e en tant que root, de sorte que cette option n'est +utilis\'ee que dans des cas bien particuliers. Malgr\'e tout, apr\`es avoir +effectu\'e les op\'erations d'initialisation pr\'eliminaires, il peut +redescendre au niveau du GroupId sp\'ecifi\'e dans cette option. +\end{description} + +Notez: de nombreuses options suppl\'ementaires vous sont pr\'esent\'ees +lorsque vous entrez {\bf ./configure \verb{--{help}, mais elles ne sont pas +impl\'ement\'ees. + +\section{Options recommand\'ees pour la plupart des syst\`emes} +\index[general]{Options recommand\'ees pour la plupart des syst\`emes } +\addcontentsline{toc}{section}{Options recommand\'ees pour la plupart des +syst\`emes} + +Pour la plupart des syst\`emes, nous recommandons de commencer avec les +options suivantes : + +\footnotesize +\begin{verbatim} +./configure \ + --enable-smartalloc \ + --sbindir=$HOME/bacula/bin \ + --sysconfdir=$HOME/bacula/bin \ + --with-pid-dir=$HOME/bacula/bin/working \ + --with-subsys-dir=$HOME/bacula/bin/working \ + --with-mysql=$HOME/mysql \ + --with-working-dir=$HOME/bacula/working +\end{verbatim} +\normalsize + +Si vous souhaitez installer Bacula dans un r\'epertoire d'installation +plut\^ot que de l'ex\'ecuter depuis le r\'epertoire de compilation, (comme le +feront les d\'eveloppeurs la plupart du temps), vous devriez aussi inclure les +options \verb{--{sbindir et \verb{--{sysconfdir avec les chemins appropri\'es. Aucune n'est +n\'ecessaire si vous ne vous servez pas de "make install'', comme c'est le +cas pour la plupart des travaux de d\'eveloppement. Le processus +d'installation va cr\'eer les r\'epertoires sbindir et sysconfdir s'ils +n'existent pas, mais il ne cr\'eera pas les r\'epertoires pid-dir, subsys-dir +ni working-dir, aussi assurez vous qu'ils existent avant de lancer Bacula. +L'exemple ci-dessous montre la fa\c{c}on de proc\'eder de Kern. + +\section{RedHat} +\index[general]{RedHat } +\addcontentsline{toc}{section}{RedHat} + +Avec SQLite: + +\footnotesize +\begin{verbatim} + +CFLAGS="-g -Wall" ./configure \ + --sbindir=$HOME/bacula/bin \ + --sysconfdir=$HOME/bacula/bin \ + --enable-smartalloc \ + --with-sqlite=$HOME/bacula/depkgs/sqlite \ + --with-working-dir=$HOME/bacula/working \ + --with-pid-dir=$HOME/bacula/bin/working \ + --with-subsys-dir=$HOME/bacula/bin/working \ + --enable-gnome \ + --enable-conio +\end{verbatim} +\normalsize + +ou + +\footnotesize +\begin{verbatim} + +CFLAGS="-g -Wall" ./configure \ + --sbindir=$HOME/bacula/bin \ + --sysconfdir=$HOME/bacula/bin \ + --enable-smartalloc \ + --with-mysql=$HOME/mysql \ + --with-working-dir=$HOME/bacula/working + --with-pid-dir=$HOME/bacula/bin/working \ + --with-subsys-dir=$HOME/bacula/bin/working + --enable-gnome \ + --enable-conio +\end{verbatim} +\normalsize + +ou une installation RedHat compl\`etement traditionnelle : + +\footnotesize +\begin{verbatim} +CFLAGS="-g -Wall" ./configure \ + --prefix=/usr \ + --sbindir=/usr/sbin \ + --sysconfdir=/etc/bacula \ + --with-scriptdir=/etc/bacula \ + --enable-smartalloc \ + --enable-gnome \ + --with-mysql \ + --with-working-dir=/var/bacula \ + --with-pid-dir=$HOME/var/run \ + --enable-conio +\end{verbatim} +\normalsize + +Notez que Bacula suppose que les r\'epertoires /var/bacula, /var/run et +/var/lock/subsys existent, ils ne seront pas cr\'ees par le processus +d'installation. + +D'autre part, avec gcc 4.0.1 20050727 (Red Hat 4.0.1-5) sur processeur AMD64 +et sous CentOS4 64 bits, un bug du compilateur g\'en\`ere du code erron\'e qui +conduit Bacula \`a des erreurs de segmentation. Typiquement, vous le rencontrerez +d'abord avec le Storage Daemon. La solution consiste \`a s'assurer que Bacula est +compil\'e sans optimisation (normalement -O2) + +\section{Solaris} +\index[general]{Solaris } +\addcontentsline{toc}{section}{Solaris} + +Pour installer Bacula depuis les sources, il vous faudra les paquetages suivants +sur votre syst\`eme (ils ne sont pas install\'es par d\'efaut) : libiconv, gcc 3.3.2, stdc++, libgcc +( pour les librairies stdc++ and gcc\_s ), make 3.8 ou plus r\'ecent. + +Il vous faudra probablement aussi ajouter /usr/local/bin et /usr/css/bin \`a PATH pour ar. + +\footnotesize +\begin{verbatim} +#!/bin/sh +CFLAGS="-g" ./configure \ + --sbindir=$HOME/bacula/bin \ + --sysconfdir=$HOME/bacula/bin \ + --with-mysql=$HOME/mysql \ + --enable-smartalloc \ + --with-pid-dir=$HOME/bacula/bin/working \ + --with-subsys-dir=$HOME/bacula/bin/working \ + --with-working-dir=$HOME/bacula/working +\end{verbatim} +\normalsize + +Comme mentionn\'e ci-dessus, le processus d'installation va cr\'eer les +r\'epertoires sbindir et sysconfdir s'ils n'existent pas, mais il ne cr\'eera +pas les r\'epertoires pid-dir, subsys-dir ni working-dir, aussi assurez vous +qu'ils existent avant de lancer Bacula. + +Notez que vous pouvez aussi avoir besoin des paquetages suivants pour installer Bacula +depuis les sources : +\footnotesize +\begin{verbatim} +SUNWbinutils, +SUNWarc, +SUNWhea, +SUNWGcc, +SUNWGnutls +SUNWGnutls-devel +SUNWGmake +SUNWgccruntime +SUNWlibgcrypt +SUNWzlib +SUNWzlibs +SUNWbinutilsS +SUNWGmakeS +SUNWlibm + +export +PATH=/usr/bin::/usr/ccs/bin:/etc:/usr/openwin/bin:/usr/local/bin:/usr/sfw/bin:/opt/sfw/bin:/usr/ucb:/usr/sbin +\end{verbatim} +\normalsize + + +\section{FreeBSD} +\index[general]{FreeBSD } +\addcontentsline{toc}{section}{FreeBSD} + +Veuillez consulter: +\elink{The FreeBSD Diary}{http://www.freebsddiary.org/bacula.php} pour une +description d\'etaill\'ee de la m\'ethode pour faire fonctionner Bacula sur +votre syst\`eme. De plus, les utilisateurs de versions de FreeBSD +ant\'erieures \`a la 4.9-STABLE du lundi 29 d\'ecembre 2003 15:18:01 qui +envisagent d'utiliser des lecteurs de bandes doivent consulter le chapitre +\ilink{Tester son lecteur de bandes}{FreeBSDTapes} de ce +manuel pour d'{\bf importantes} informations sur la configuration des lecteurs +pour qu'ils soient compatibles avec Bacula. + +Si vous utilisez Bacula avec MySQL, vous devriez prendre garde \`a compiler +MySQL avec les threads natifs de FreeBSD plut\^ot qu'avec ceux de Linux, car +c'est avec ceux l\`a qu'est compil\'e Bacula et le m\'elange des deux ne +fonctionnera probablement pas. + +\section{Win32} +\index[general]{Win32 } +\addcontentsline{toc}{section}{Win32} + +Pour installer la version binaire Win32 du File Daemon, consultez le chapitre +\ilink{ Installation sur syst\`emes Win32}{_ChapterStart7} de ce +document. + +\section{Syst\`emes Windows avec CYGWIN install\'e} +\label{Win32} +\index[general]{Syst\`emes Windows avec CYGWIN install\'e } +\addcontentsline{toc}{section}{Syst\`emes Windows avec CYGWIN install\'e} + +A partir de la version 1.34, Bacula n'utilise plus CYGWIN pour le client +Win32. Il est cependant encore compil\'e sous un environnement CYGWIN -- Bien +que vous puissiez probablement le faire avec seulement VC Studio. Si vous +souhaitez compiler le client Win32 depuis les sources, il vous faudra +Microsoft C++ version 6.0 ou sup\'erieur. Dans les versions de Bacula +ant\'erieures \`a la 1.33, CYGWIN \'etait utilis\'e. + +Notez qu'en d\'epit du fait que la plupart des \'el\'ements de Bacula puissent +compiler sur les syst\`emes Windows, la seule partie que nous avons test\'ee +et utilis\'ee est le File Daemon. + +Finalement, vous devriez suivre les instructions d'installation de la section +\ilink{Win32 Installation sur syst\`emes Win32}{_ChapterStart7} de ce +document en occultant la partie qui d\'ecrit la d\'ecompression de la version +binaire. + +\section{Le script Configure de Kern} +\index[general]{Le script Configure de Kern } +\index[general]{Kern!Le script Configure de } +\addcontentsline{toc}{section}{Le script Configure de Kern} + +Voici le script que j'utilise pour compiler sur mes machines Linux de +"production'': + +\footnotesize +\begin{verbatim} +#!/bin/sh +# This is Kern's configure script for Bacula +CFLAGS="-g -Wall" \ + ./configure \ + --sbindir=$HOME/bacula/bin \ + --sysconfdir=$HOME/bacula/bin \ + --enable-smartalloc \ + --enable-gnome \ + --with-pid-dir=$HOME/bacula/bin/working \ + --with-subsys-dir=$HOME/bacula/bin/working \ + --with-mysql=$HOME/mysql \ + --with-working-dir=$HOME/bacula/bin/working \ + --with-dump-email=$USER \ + --with-smtp-host=mail.your-site.com \ + --with-baseport=9101 +exit 0 +\end{verbatim} +\normalsize + +Notez que je fixe le port de base \`a 9101, ce qui signifie que Bacula +utilisera le port 9101 pour la console Director, le port 9102 pour le File +Daemon, et le 9103 pour le Storage Daemon. Ces ports devraient \^etre +disponibles sur tous les syst\`emes \'etant donn\'e qu'ils ont \'et\'e +officiellement attribu\'es \`a Bacula par l'IANA (Internet Assigned Numbers +Authority). Nous recommandons fortement de n'utiliser que ces ports pour +\'eviter tout conflit avec d'autres programmes. Ceci est en fait la +configuration par d\'efaut si vous n'utilisez pas l'option {\bf +\verb{--{with-baseport}. + +Vous pouvez aussi ins\'erer les entr\'ees suivantes dans votre fichier {\bf +/etc/services} de fa\c{c}on \`a rendre les connections de Bacula plus +ais\'ees \`a rep\'erer (i.e. netstat -a): + +\footnotesize +\begin{verbatim} +bacula-dir 9101/tcp +bacula-fd 9102/tcp +bacula-sd 9103/tcp +\end{verbatim} +\normalsize + +\section{Installer Bacula} +\index[general]{Installer Bacula } +\index[general]{Bacula!Installer } +\addcontentsline{toc}{section}{Installer Bacula} + +Avant de personnaliser vos fichiers de configuration, vous voudrez installer +Bacula dans son r\'epertoire d\'efinitif. tapez simplement: + +\footnotesize +\begin{verbatim} +make install +\end{verbatim} +\normalsize + +Si vous avez pr\'ec\'edemment install\'e Bacula, les anciens binaires seront +\'ecras\'es, mais les anciens fichiers de configuration resteront inchang\'es, +et les "nouveaux'' recevront l'extension {\bf .new}. G\'en\'eralement, si +vous avez d\'ej\`a install\'e et ex\'ecut\'e Bacula, vous pr\'ef\`ererez +supprimer ou ignorer les fichiers de configuration avec l'extension {\bf .new} + + +\section{Compiler un File Daemon (ou Client)} +\index[general]{Compiler un File Daemon (ou Client) } +\index[general]{Client!Compiler un File Daemon ou } +\addcontentsline{toc}{section}{Compiler un File Daemon (ou Client)} + +Si vous ex\'ecutez le Director et le Storage Daemon sur une machine et si vous +voulez sauvegarder une autre machine, vous devez avoir un File Daemon sur +cette machine. Si la machine et le syst\`eme sont identiques, vous pouvez +simplement copier le binaire du File Daemon {\bf bacula-fd} ainsi que son +fichier de configuration {\bf bacula-fd.conf}, puis modifier le nom et le mot +de passe dans {\bf bacula-fd.conf} de fa\c{c}on \`a rendre ce fichier unique. +Veillez \`a faire les modifications correspondantes dans le fichier de +configuration du Director ({\bf bacula-dir.conf}). + +Si les architectures, les syst\`emes, ou les versions de syst\`emes +diff\`erent, il vous faudra compiler un File Daemon sur la machine cliente. +Pour ce faire, vous pouvez utiliser la m\^eme commande {\bf ./configure} que +celle utilis\'ee pour construire le programme principal, soit en partant d'une +copie fraiche du r\'epertoire des sources, soit en utilisant {\bf make\ +distclean} avant de lancer {\bf ./configure}. + +Le File Daemon n'ayant pas d'acc\`es au catalogue, vous pouvez supprimer les +option {\bf \verb{--{with-mysql} ou {\bf \verb{--{with-sqlite}. Ajoutez l'option {\bf +\verb{--{enable-client-only}. Ceci va compiler seulement les librairies et programmes +clients, et donc \'eviter d'avoir \`a installer telle ou telle base de +donn\'ees. Lancez make avec cette configuration, et seul le client sera +compil\'e. +\label{autostart} + +\section{D\'emarrage automatique des Daemons} +\index[general]{Daemons!D\'emarrage automatique des } +\index[general]{D\'emarrage automatique des Daemons } +\addcontentsline{toc}{section}{D\'emarrage automatique des Daemons} + +Si vous souhaitez que vos {\it daemons} soient lanc\'es automatiquement au +d\'emarrage de votre syst\`eme (une bonne id\'ee !), une \'etape +suppl\'ementaire est requise. D'abord, le processus ./configure doit +reconna{\^\i}tre votre syst\`eme -- ce qui signifie que ce doit \^etre une +plate-forme support\'ee et non {\bf inconnue}, puis vous devez installer les +fichiers d\'ependants de la plate-forme comme suit : + +\footnotesize +\begin{verbatim} +(devenez root) +make install-autostart +\end{verbatim} +\normalsize + +Notez que la fonction d'autod\'emarrage n'est impl\'ement\'ee que pour les +syst\`emes que nous supportons officiellement (actuellement FreeBSD, RedHat +Linux, et Solaris), et n'a \'et\'e pleinement test\'ee que sur RedHat Linux. + +{\bf make install-autostart} installe les scripts de d\'emarrage apropri\'es +ainsi que les liens symboliques n\'ecessaires. Sur RedHat Linux, Ces scripts +r\'esident dans {\bf /etc/rc.d/init.d/bacula-dir} {\bf +/etc/rc.d/init.d/bacula-fd}, et {\bf /etc/rc.d/init.d/bacula-sd}. Toutefois, +leur localisation exacte d\'epend de votre syst\`eme d'exploitation. + +Si vous n'installez que le File Daemon, tapez: + +\footnotesize +\begin{verbatim} +make install-autostart-fd +\end{verbatim} +\normalsize + +\section{Autres notes concernant la compilation} +\index[general]{Autres notes concernant la compilation } +\index[general]{Compilation!Autres notes concernant la } +\addcontentsline{toc}{section}{Autres notes concernant la compilation} + +Pour recompiler tout ex\'ecutable, tapez + +\footnotesize +\begin{verbatim} +make +\end{verbatim} +\normalsize + +dans le r\'epertoire correspondant.. Afin d'\'eliminer tous les objets et +binaires (y compris les fichiers temporaires nomm\'es 1,2 ou 3 qu'utilise +Kern), tapez + +\footnotesize +\begin{verbatim} +make clean +\end{verbatim} +\normalsize + +Pour un nettoyage exhaustif en vue de distribution, entrez: + +\footnotesize +\begin{verbatim} +make distclean +\end{verbatim} +\normalsize + +Notez que cette commande supprime les Makefiles. Elle est en principe +lanc\'ee depuis la racine du r\'epertoire des sources pour les pr\'eparer \`a +la distribution. Pour revenir de cet \'etat, vous devez r\'eex\'ecuter la +commande {\bf ./configure} \`a la racine des sources puisque tous les +Makefiles ont \'et\'e d\'etruits. + +Pour ajouter un nouveau fichier dans un sous-r\'epertoire, \'editez +Makefile.in dans ce sous-r\'epertoire, puis faites un simple {\bf make}. Dans +la plupart des cas, le make reconstruira le Makefile \`a partir du nouveau +Makefile.in. Dans certains cas, il peut \^etre n\'ecessaire d'ex\'ecuter {\bf +make} une deuxi\`eme fois. Dans les cas extr\`emes, remontez \`a la racine des +sources et entrez {\bf make Makefiles}. + +Pour ajouter des d\'ependances: + +\footnotesize +\begin{verbatim} +make depend +\end{verbatim} +\normalsize + +La commande {\bf make depend} ins\`ere les fichiers d'en-t\^etes de +d\'ependances aux Makefile et Makefile.in pour chaque fichier objet. Cette +commande devrait \^etre lanc\'ee dans chaque r\'epertoire o\`u vous modifiez +les d\'ependances. En principe, il suffit de l'ex\'ecuter lorsque vous ajoutez +ou supprimez des sources ou fichiers d'en-t\^etes. {\bf make depend} est +invoqu\'e automatiquement durant le processus de configuration. + +Pour installer: + +\footnotesize +\begin{verbatim} +make install +\end{verbatim} +\normalsize + +En principe, vous n'utilisez pas cette commande si vous \^etes en train de +d\'evelopper Bacula, mais si vous vous appr\'etez \`a l'ex\'ecuter pour +sauvegarder vos syst\`emes. + +Apr\`es avoir lanc\'e {\bf make install}, les fichiers suivants seront +install\'es sur votre syst\`eme (\`a peu de choses pr\`es). La liste exacte +des fichiers install\'es et leur localisation d\'epend de votre commande {\bf +c./configure} (e.g. gnome-console et gnome-console.conf ne sont pas +install\'es si vous ne configurez pas GNOME. De m\^eme, si vous utilisez +SQLite plut\^ot que MySQL, certains fichiers seront diff\'erents. + +\footnotesize +\begin{verbatim} +bacula +bacula-dir +bacula-dir.conf +bacula-fd +bacula-fd.conf +bacula-sd +bacula-sd.conf +bacula-tray-monitor +tray-monitor.conf +bextract +bls +bscan +btape +btraceback +btraceback.gdb +bconsole +bconsole.conf +create_mysql_database +dbcheck +delete_catalog_backup +drop_bacula_tables +drop_mysql_tables +fd +gnome-console +gnome-console.conf +make_bacula_tables +make_catalog_backup +make_mysql_tables +mtx-changer +query.sql +bsmtp +startmysql +stopmysql +bwx-console +bwx-console.conf +\end{verbatim} +\normalsize + +\label{monitor} + +\section{Installer Tray Monitor} +\index[general]{Monitor!Installer Tray } +\index[general]{Installer Tray Monitor } +\addcontentsline{toc}{section}{Installer Tray Monitor} + +Le Tray Monitor est d\'ej\`a install\'e si vous avez utilis\'e l'option {\bf +\verb{--{enable-tray-monitor} de la commande configure et ex\'ecut\'e {\bf make +install}. + +Comme vous n'ex\'ecutez pas votre environnement graphique en tant que root (si +vous le faites, vous devriez changer cette mauvaise habitude), n'oubliez pas +d'autoriser votre utilisateur \`a lire {\bf tray-monitor.conf}, et ex\'ecuter +{\bf bacula-tray-monitor} (ceci ne constitue pas une faille de s\'ecurit\'e). + +Puis, connectez vous \`a votre environnement graphique (KDE, Gnome, ou autre), +lancez {\bf bacula-tray-monitor} avec votre utilisateur et observez si l'icone +d'une cartouche appara{\^\i}t quelque part sur l'\'ecran, usuellement dans la +barre des t\^aches. +Sinon, suivez les instructions suivantes relatives \`a votre gestionnaire de +fen\^etres. + +\subsection{GNOME} +\index[general]{GNOME } +\addcontentsline{toc}{subsection}{GNOME} + +System tray, ou zone de notification si vous utilisez la terminologie GNOME, +est support\'e par GNOME depuis la version 2.2. Pour l'activer, faites un +click droit sur un de vos espaces de travail, ouvrez le menu {\bf Ajouter \`a +ce bureau}, puis {\bf Utilitaire} et enfin, cliquez sur {\bf Zone de +notification}. (NDT: A valider) + +\subsection{KDE} +\index[general]{KDE } +\addcontentsline{toc}{subsection}{KDE} + +System tray est support\'e par KDE depuis la version 3.1. Pour l'activer, +faites un click droit sur la barre de t\^aches, ouvrez le menu {\bf Ajouter}, +puis {\bf Applet}, enfin cliquez sur {\bf System Tray}. + +\subsection{Autres gestionnaires de fen\^etres} +\index[general]{Autres gestionnaires de fen\^etres } +\addcontentsline{toc}{subsection}{Autres gestionnaires de fen\^etres} + +Lisez la documentation pour savoir si votre gestionnaire de fen\^etres +supporte le standard {\it systemtray} de FreeDesktop, et comment l'activer le +cas \'ech\'eant. + +\section{Modifier les fichiers de configuration de Bacula} +\index[general]{Modifier les fichiers de configuration de Bacula } +\index[general]{Bacula!Modifier les fichiers de configuration de } +\addcontentsline{toc}{section}{Modifier les fichiers de configuration de +Bacula} + +Consultez le chapitre +\ilink{Configurer Bacula}{_ChapterStart16} de ce manuel pour les +instructions de configuration de Bacula. diff --git a/docs/manuals/fr/install/latex2html-init.pl b/docs/manuals/fr/install/latex2html-init.pl new file mode 100644 index 00000000..14b5c319 --- /dev/null +++ b/docs/manuals/fr/install/latex2html-init.pl @@ -0,0 +1,10 @@ +# This file serves as a place to put initialization code and constants to +# affect the behavior of latex2html for generating the bacula manuals. + +# $LINKPOINT specifies what filename to use to link to when creating +# index.html. Not that this is a hard link. +$LINKPOINT='"$OVERALL_TITLE"'; + + +# The following must be the last line of this file. +1; diff --git a/docs/manuals/fr/install/messagesres.tex b/docs/manuals/fr/install/messagesres.tex new file mode 100644 index 00000000..49d313e3 --- /dev/null +++ b/docs/manuals/fr/install/messagesres.tex @@ -0,0 +1,347 @@ +%% +%% + +\chapter{La ressource Messages} +\label{_ChapterStart15} +\index[general]{Ressource!Messages} +\index[general]{Messages Ressource} +\addcontentsline{toc}{section}{Ressource Messages} + +\section{La ressource Messages} +\label{MessageResource} +\index[general]{Ressource!Messages} +\index[general]{Messages Ressource} +\addcontentsline{toc}{section}{La ressource Messages} + +La ressource Messages d\'efinit la fa\c{c}on dont les messages doivent \^etre construits +et vers quelles destinations ils doivent \^etre transmis. + +Bien que chaque {\it daemon} int\`egre un gestionnaire de messages pleinement +fonctionnel, vous choisirez certainement de centraliser les messages appropri\'es +des File Daemons et du Storage Daemon vers le Director. Ainsi, tous les messages +associ\'es \`a un job donn\'e peuvent \^etre combin\'es et envoy\'es en un simple courrier +\'electronique vers l'utilisateur, ou enregistr\'e dans quelque fichier de logs. + +Chaque message g\'en\'er\'e par un {\it daemon} Bacula poss\`ede un type associ\'e tel +que INFO, WARNING, ERROR, FATAL, etc. La ressource Messages vous permet de +stipuler les types de messages que vous voulez voir, et o\`u les envoyer. De plus, +un message peut \^etre exp\'edi\'e vers plusieurs destinations. Par exemple, vous +pouvez faire en sorte quque tous les messages d'erreur soient consign\'es dans un +fichier de logs tout en vous \'etant envoy\'es par courrier \'elecronique. En +d\'efinissant plusieurs ressources Messages, vous pouvez profiter de diff\'erents +modes de prise en charge pour chaque type de job (par exemple, selon qu'il +s'agit d'une full ou d'un incr\'ementale). + +En g\'en\'eral, les messages sont attach\'es \`a un job et sont inclus dans le rapport de job. +Il existe de rares situations o\`u ce n'est pas possible, par exemple lorsqu'aucun +job n'est en cours d'ex\'ecution, ou si une erreur de communication se produit +entre un daemon et le Director. Dans ce genre de situations, le message demeure +dans le syst\`eme et devrait \^etre purg\'e \`a la fin job suivant. Cependant, comme de tels +messages ne sont pas attach\'es \`a un job, tous ceux qui sont envoy\'es par courrier +\'electronique sont envoy\'es \`a {\bf /usr/lib/sendmail}. Si sur votre syst\`eme, comme c'est +le cas de FreeBSD, sendmail r\'eside en un autre emplacement, veillez \`a le lier +depuis l'emplacement ci-dessus. + +Les enregistrements contenus dans une ressource Messages consistent en une +sp\'ecification de {\bf destination} suivie d'une liste de types de messages +{\bf message-types} au format : + +\begin{description} + +\item [destination = message-type1, message-type2, message-type3, ... ] + \index[dir]{destination} + \end{description} + +ou, pour ces destinations qui n\'ecessitent de sp\'ecifier une adresse (e-mail, par exemple) : + +\begin{description} + +\item [destination = address = message-type1, message-type2, + message-type3, ... ] + \index[dir]{destination} + +o\`u {\bf destination} est l'un des mots-clef pr\'ed\'efinis qui pr\'ecise o\`u le message +doit \^etre exp\'edi\'e ({\bf stdout}, {\bf file}, ...), {\bf message-type} est l'un des +mots-clef pr\'ed\'efinis qui pr\'ecise le type de messages g\'en\'er\'e par Bacula ({\bf ERROR}, +{\bf WARNING}, {\bf FATAL}, ...) et {\bf address} varie selon le mot clef {\bf destination} +mais peut typiquement \^etre une adresse de courrier \'electronique ou un nom de fichier. + +\end{description} + +Voici la liste des directives disponibles pour d\'efinir des ressources Messages : + + +\begin{description} + +\item [Messages] + \index[dir]{Messages} + D\'ebut des enregistrements de Messages + +\item [Name = \lt{}name\gt{}] + \index[dir]{Name} + Le nom de la ressource Message. Ce nom sera utilis\'e pour lier cette ressource +Message \`a un job et/ou au un daemon. + +\label{mailcommand} + +\item [MailCommand = \lt{}command\gt{}] + \index[dir]{MailCommand} +En l'absence de cette directive, Bacula enverra tous ses messages avec la +commande suivante : + +{\bf mail -s "Bacula Message" \lt{}recipients\gt{}} +Dans de nombreusx cas, selon votre machine, cette commande peut ne pas fonctionner. +La directive {\bf MailCommand} vous permet de stipuler pr\'ecis\'ement la fa\c{c}on +d'envoyer vos courrier \'electroniques. Lors de l'ex\'ecution de la commande +{\bf command}, sp\'ecifi\'ee entre guillemets, les substitutions suivantes sont +effectu\'ees : + +\begin{itemize} + \item \%\% = \% + \item \%c = Le nom du client + \item \%d = Le nom du Director + \item \%e = Le code de sortie du job (OK, Error, ...) + \item \%i = L'Id du Job + \item \%j = Le nom unique du job + \item \%l = Le niveau (Full, differential, ...) du job + \item \%n = Le om du job + \item \%r = Les destinataires + \item \%t = Le type du job (Backup, verify, ...) +\end{itemize} + +Voici la commande que j'utilise (Kern) : + +{\bf mailcommand = "/home/kern/bacula/bin/bsmtp -h mail.example.com -f +\textbackslash{}"\textbackslash{}(Bacula\textbackslash{}) +\%r\textbackslash{}" -s \textbackslash{}"Bacula: \%t \%e of \%c +\%l\textbackslash{}" \%r"} + +Notez que la commande enti\`ere devrait appara\^itre sur une seulle ligne plut\^ot +que d\'ecoup\'ee comme ici pour des raisons de pr\'esentation. + +Le programme {\bf bsmtp} est fourni en tant que partie de Bacula. Pour plus +de d\'etails, consultez la section \ilink{ bsmtp -- Personnaliser l'envoi +de vos message par courrier \'electronique}{bsmtp}. Testez soigneusement +toute commande {\bf mailcommand} pour vous assurer que votre passerelle +bsmtp accepte le format d'adressage que vous utilisez. Certains programmes +tels Exim peut se montrer tr\`es s\'electif en ce qui concerne les format +autoris\'es, particuli\`erement en ce qui concerne le champ "from". + +\item [OperatorCommand = \lt{}command\gt{}] + \index[fd]{OperatorCommand} + Cette directive est analogue \`a {\bf MailCommand}, mais elle est utilis\'ee pour + les messages destin\'es \`a l'op\'erateur. Les substitutions effectu\'ees pour la + directive {\bf MailCommand} sont aussi effectu\'ees pour celle-ci. Normalement, + vous mettrez ici la m\^eme valeur que pour {\bf MailCommand}. + +\item [Debug = \lt{}debug-level\gt{}] + \index[fd]{Debug} + Cette directive r\`egle le niveau de d\'ebogage des messages. C'est un entier. + Plus sa valeur est grande, plus grande est la quantit\'e d'informations de + d\'ebogages produites. Nous vous conseillons de ne pas utiliser cette directive + car elle sera bient\^ot obsol\`ete. + +\item [\lt{}destination\gt{} = \lt{}message-type1\gt{}, + \lt{}message-type2\gt{}, ...] + \index[fd]{\lt{}destination\gt{}} + +O\`u la {\bf destination} peut \^etre l'une des suivantes : + +\begin{description} + +\item [stdout] + \index[fd]{stdout} + Envoie le message vers la sortie standard. + +\item [stderr] + \index[fd]{stderr} + Envoie le message vers l'erreur standard + +\item [console] + \index[console]{console} + Envoie le message vers la console Bacula. Ces messages sont gard\'es en attente + jusqu'\`a ce que la console contacte le Director. +\end{description} + +\item {\bf \lt{}destination\gt{} = \lt{}address\gt{} = + \lt{}message-type1\gt{}, \lt{}message-type2\gt{}, ...} + \index[console]{\lt{}destination\gt{}} + +O\`u {\bf address} d\'epend de la {\bf destination}, qui peut \^etre l'une des suivantes : + +\begin{description} + +\item [director] + \index[dir]{director} + Envoie le message vers le Director dont le nom est sp\'ecifi\'e dans le champ + {\bf address}. Notez que dans l'impl\'ementation actuelle, le nom du Director + est ignor\'e, le message \'etant envoy\'e au Directr qui a lanc\'e le job. + +\item [file] + \index[dir]{file} + Envoie le message vers le fichier d\'esign\'e dans le champ {\bf address}. Si le + fichier existe, il est \'ecras\'e. + +\item [append] + \index[dir]{append} + Ajoute le message \`a la suite du fichier d\'esign\'e dans le champ {\bf address}. + Si le fichier n'existe pas encore, il est cr\'e\'e. + +\item [syslog] + \index[fd]{syslog} + Envoie le message vers le syst\`eme de journalisation (syslog) en utilisant le + service d\'esign\'e par le champ {\bf address} Notez que, pour le moment, le champ + {\bf address} est ignor\'e, et que le message est toujours envoy\'e au service + LOG\_DAEMON avec le niveau LOG\_ERR. Consultez la page {\bf man 3 syslog} + pour plus de d\'etails. Exemple : + +\begin{verbatim} + syslog = all, !skipped, !saved +\end{verbatim} + +\item [mail] + \index[fd]{mail} + Exp\'edie le message vers les adresses \'electroniques + sp\'ecifi\'ees dans le champ {\bf address} (s\'epar\'ees par des points-virgule). + Les messages sont rassembl\'es au cours du job, puis exp\'edi\'es lorsqu'il prend + fin en un seul courrier \'electronique. L'avantage de cette Destination est + que vous recevez une notification de chaque job ex\'ecut\'e. Toutefois, si vous + sauvegardez cinq ou dix machines chaque nuit, la quantit\'e de courrier + \'electronique peut devenir importante. Certains utilisateurs mettent en oeuvre + des filtres de courrier tels {\bf procmail} pour classer automatiquement ces + courriers en fonction des codes de fin de job (voyez la commande {\bf mailcommand} + +\item [mail on error] + \index[fd]{mail on error} + Exp\'edie le message vers les adresses \'electroniques + sp\'ecifi\'ees dans le champ {\bf address} (s\'epar\'ees par des points-virgule) + si le job se termine avec un code d'erreur. Les messages MailOnError sont + rassembl\'es au cours du job, puis exp\'edi\'es lorsqu'il prend fin en un seul + courrier \'electronique. Cette Destination diff\`ere de la Destination {\bf mail} + en ce que si le job s'ach\`eve normalement, le message est compl\`etement + abandonn\'e (pour cette Destination). En utilisant d'autres Destinations, telles + que {\bf append}, vous pouvez vous assurer que les informations de sorties + ne seront pas perdues m\^eme si le job se termine normalement. + +\item [operator] + \index[fd]{operator} + Exp\'edie le message vers les adresses \'electroniques + sp\'ecifi\'ees dans le champ {\bf address} (s\'epar\'ees par des points virgule). + Cette directive est similaire \`a {\bf mail} d\'ecrite plus haut, sauf que + chaque message est envoy\'e aussit\^ot re\c{c}u, de sorte qu'il y a un courrier + \'electronique par message . Ceci est surtout utile pour les messages de + type {\bf mount} (voir ci-dessous). + +\end{description} + Pour toutes les Destinations, le champ "type de message" {\bf message-type} est + une liste des types (ou classes) de messages suivants s\'epar\'es par des + points-virgule : + +\begin{description} + +\item [info] + \index[fd]{info} + Messages d'information g\'en\'erale. + +\item [warning] + \index[fd]{warning} + Messages d'avertissement. En g\'en\'eral, il s'agit de quelque situation inhabituelle + sans toutefois \^etre tr\`es s\'erieuse. + +\item [error] + \index[fd]{error} + Messages d'erreur non-fatale. Le job se poursuit. Tout message d'erreur devrait + \^etre suivi d'investigations, car il signifie que quelque chose est all\'e de travers. + +\item [fatal] + \index[fd]{fatal} + Messages d'erreur fatale. Ces erreurs pr\'ecipitent la fin du job. + +\item [terminate] + \index[fd]{terminate} + Messages g\'en\'er\'es lorsque le daemon s'arr\`ete. + +\item [saved] + \index[fd]{saved} + Fichiers sauvegard\'es normalement. + +\item [notsaved] + \index[fd]{notsaved} + Fichiers non sauvegard\'es en raison d'une erreur, en g\'en\'eral, parce que le + fichier n'a pu \^etre acc\'ed\'e (il n'existait pas ou n'\'etait pas mont\'e). + +\item [skipped] + \index[fd]{skipped} + Fichiers qui ont \'et\'e laiss\'es de cot\'e en raison d'une option pos\'ee par un + utilisateur (par exemple le niveau d'une sauvegarde ou une option + d'exclusion. Ceci n'est pas consid\'er\'e comme une condition d'erreur au m\^eme + titre que pour le type {\bf notsaved} puisque le fichier de configuration + stipule explicitement que ces fichiers ne doivent pas \^etre sauvegard\'es. + Des cas typiques de fichiers de type {\bf skipped} : fichiers inchang\'es + lors d'une incr\'ementale, sous-r\'epertoires si l'option {\bf no recursion} + est activ\'ee... + +\item [mount] + \index[dir]{mount} + Montage d'un volume ou intervention d'un op\'erateur requis par le Storage Daemon. + Ces requ\^etes n\'ecessitent une intervention sp\'ecifique de l'op\'erateur pour que le + job puisse se poursuivre. + +\item [restored] + \index[dir]{restored} + La liste, fa\c{c}on {\bf ls}, de tous les fichiers restaur\'es est envoy\'ee vers + cette classe de messages. + +\item [all] + \index[fd]{all} + Tous les types de messages. + +\item [*security] + \index[fd]{*security} + Messages d'information ou d'avertissement relatifs \`a la s\'ecurit\'e, + essentiellement les tentatives de connection non-autoris\'ees. +\end{description} + +\end{description} + +Voici un exemple d'une d\'efinition de ressource Messages valide, o\`u tous les +messages sont envoy\'es par courrier \'electronique \`a enforcement@sec.com \`a +l'exception de ceux concernant les fichiers explicitement exclus (skipped), +et des messages d'arr\^et de daemon (terminate). De plus, tous les messages +de type mount sont envoy\'es \`a l'op\'erateur (courrier \`a enforcement@sec.com). +Enfin, tous les messages autres que ceux relatifs aux fichiers explicitement +exclus et aux fichiers sauvegard\'es sont envoy\'es vers la console : + +\footnotesize +\begin{verbatim} +Messages { + Name = Standard + mail = enforcement@sec.com = all, !skipped, !terminate + operator = enforcement@sec.com = mount + console = all, !skipped, !saved +} +\end{verbatim} +\normalsize + +A l'exception de l'adresse \'electronique (modifi\'ee pour \'eviter le spam), +voici la ressource Message du Director de Kern. Notez que les commandes +{\bf mailcommand} et {\bf operatorcommand} sont sur une seule ligne et +non coup\'ees comme ici pour des besoins de mise en page. + +\footnotesize +\begin{verbatim} +Messages { + Name = Standard + mailcommand = "bacula/bin/bsmtp -h mail.example.com \ + -f \"\(Bacula\) %r\" -s \"Bacula: %t %e of %c %l\" %r" + operatorcommand = "bacula/bin/bsmtp -h mail.example.com \ + -f \"\(Bacula\) %r\" -s \"Bacula: Intervention needed \ + for %j\" %r" + MailOnError = security@example.com = all, !skipped, \ + !terminate + append = "bacula/bin/log" = all, !skipped, !terminate + operator = security@example.com = mount + console = all, !skipped, !saved +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/install/monitorconf.tex b/docs/manuals/fr/install/monitorconf.tex new file mode 100644 index 00000000..20c70b9d --- /dev/null +++ b/docs/manuals/fr/install/monitorconf.tex @@ -0,0 +1,341 @@ +%% +%% + +\chapter{Monitor Configuration} +\label{_MonitorChapter} +\index[general]{Monitor Configuration } +\index[general]{Configuration!Monitor } + +The Monitor configuration file is a stripped down version of the Director +configuration file, mixed with a Console configuration file. It simply +contains the information necessary to contact Directors, Clients, and Storage +daemons you want to monitor. + +For a general discussion of configuration file and resources including the +data types recognized by {\bf Bacula}, please see the +\ilink{Configuration}{ConfigureChapter} chapter of this manual. + +The following Monitor Resource definition must be defined: + +\begin{itemize} +\item + \ilink{Monitor}{MonitorResource} -- to define the Monitor's + name used to connect to all the daemons and the password used to connect to +the Directors. Note, you must not define more than one Monitor resource in +the Monitor configuration file. +\item At least one + \ilink{Client}{ClientResource1}, + \ilink{Storage}{StorageResource1} or +\ilink{Director}{DirectorResource2} resource, to define the +daemons to monitor. +\end{itemize} + +\section{The Monitor Resource} +\label{MonitorResource} +\index[general]{Monitor Resource } +\index[general]{Resource!Monitor } + +The Monitor resource defines the attributes of the Monitor running on the +network. The parameters you define here must be configured as a Director +resource in Clients and Storages configuration files, and as a Console +resource in Directors configuration files. + +\begin{description} + +\item [Monitor] + \index[fd]{Monitor } + Start of the Monitor records. + +\item [Name = \lt{}name\gt{}] + \index[fd]{Name } + Specify the Director name used to connect to Client and Storage, and the +Console name used to connect to Director. This record is required. + +\item [Password = \lt{}password\gt{}] + \index[fd]{Password } + Where the password is the password needed for Directors to accept the Console +connection. This password must be identical to the {\bf Password} specified +in the {\bf Console} resource of the +\ilink{Director's configuration}{DirectorChapter} file. This +record is required if you wish to monitor Directors. + +\item [Refresh Interval = \lt{}time\gt{}] + \index[fd]{Refresh Interval } + Specifies the time to wait between status requests to each daemon. It can't +be set to less than 1 second, or more than 10 minutes, and the default value +is 5 seconds. +% TODO: what is format of the time? +% TODO: should the digits in this definition be spelled out? should +% TODO: this say "time-period-specification" above??) +\end{description} + +\section{The Director Resource} +\label{DirectorResource2} +\index[general]{Director Resource } +\index[general]{Resource!Director } + +The Director resource defines the attributes of the Directors that are +monitored by this Monitor. + +As you are not permitted to define a Password in this resource, to avoid +obtaining full Director privileges, you must create a Console resource in the +\ilink{Director's configuration}{DirectorChapter} file, using the +Console Name and Password defined in the Monitor resource. To avoid security +problems, you should configure this Console resource to allow access to no +other daemons, and permit the use of only two commands: {\bf status} and {\bf +.status} (see below for an example). + +You may have multiple Director resource specifications in a single Monitor +configuration file. + +\begin{description} + +\item [Director] + \index[fd]{Director } + Start of the Director records. + +\item [Name = \lt{}name\gt{}] + \index[fd]{Name } + The Director name used to identify the Director in the list of monitored +daemons. It is not required to be the same as the one defined in the Director's +configuration file. This record is required. + +\item [DIRPort = \lt{}port-number\gt{}] + \index[fd]{DIRPort } + Specify the port to use to connect to the Director. This value will most +likely already be set to the value you specified on the {\bf +\verb:--:with-base-port} option of the {\bf ./configure} command. This port must be +identical to the {\bf DIRport} specified in the {\bf Director} resource of +the +\ilink{Director's configuration}{DirectorChapter} file. The +default is 9101 so this record is not normally specified. + +\item [Address = \lt{}address\gt{}] + \index[fd]{Address } + Where the address is a host name, a fully qualified domain name, or a network +address used to connect to the Director. This record is required. +\end{description} + +\section{The Client Resource} +\label{ClientResource1} +\index[general]{Resource!Client } +\index[general]{Client Resource } + +The Client resource defines the attributes of the Clients that are monitored +by this Monitor. + +You must create a Director resource in the +\ilink{Client's configuration}{FiledConfChapter} file, using the +Director Name defined in the Monitor resource. To avoid security problems, you +should set the {\bf Monitor} directive to {\bf Yes} in this Director resource. + + +You may have multiple Director resource specifications in a single Monitor +configuration file. + +\begin{description} + +\item [Client (or FileDaemon)] + \index[fd]{Client (or FileDaemon) } + Start of the Client records. + +\item [Name = \lt{}name\gt{}] + \index[fd]{Name } + The Client name used to identify the Director in the list of monitored +daemons. It is not required to be the same as the one defined in the Client's +configuration file. This record is required. + +\item [Address = \lt{}address\gt{}] + \index[fd]{Address } + Where the address is a host name, a fully qualified domain name, or a network +address in dotted quad notation for a Bacula File daemon. This record is +required. + +\item [FD Port = \lt{}port-number\gt{}] + \index[fd]{FD Port } + Where the port is a port number at which the Bacula File daemon can be +contacted. The default is 9102. + +\item [Password = \lt{}password\gt{}] + \index[fd]{Password } + This is the password to be used when establishing a connection with the File +services, so the Client configuration file on the machine to be backed up +must have the same password defined for this Director. This record is +required. +\end{description} + +\section{The Storage Resource} +\label{StorageResource1} +\index[general]{Resource!Storage } +\index[general]{Storage Resource } + +The Storage resource defines the attributes of the Storages that are monitored +by this Monitor. + +You must create a Director resource in the +\ilink{Storage's configuration}{StoredConfChapter} file, using the +Director Name defined in the Monitor resource. To avoid security problems, you +should set the {\bf Monitor} directive to {\bf Yes} in this Director resource. + + +You may have multiple Director resource specifications in a single Monitor +configuration file. + +\begin{description} + +\item [Storage] + \index[fd]{Storage } + Start of the Storage records. + +\item [Name = \lt{}name\gt{}] + \index[fd]{Name } + The Storage name used to identify the Director in the list of monitored +daemons. It is not required to be the same as the one defined in the Storage's +configuration file. This record is required. + +\item [Address = \lt{}address\gt{}] + \index[fd]{Address } + Where the address is a host name, a fully qualified domain name, or a network +address in dotted quad notation for a Bacula Storage daemon. This record is +required. + +\item [SD Port = \lt{}port\gt{}] + \index[fd]{SD Port } + Where port is the port to use to contact the storage daemon for information +and to start jobs. This same port number must appear in the Storage resource +of the Storage daemon's configuration file. The default is 9103. + +\item [Password = \lt{}password\gt{}] + \index[sd]{Password } + This is the password to be used when establishing a connection with the +Storage services. This same password also must appear in the Director +resource of the Storage daemon's configuration file. This record is required. + +\end{description} + +\section{Tray Monitor Security} +\index[general]{Tray Monitor Security} + +There is no security problem in relaxing the permissions on +tray-monitor.conf as long as FD, SD and DIR are configured properly, so +the passwords contained in this file only gives access to the status of +the daemons. It could be a security problem if you consider the status +information as potentially dangerous (I don't think it is the case). + +Concerning Director's configuration: \\ +In tray-monitor.conf, the password in the Monitor resource must point to +a restricted console in bacula-dir.conf (see the documentation). So, if +you use this password with bconsole, you'll only have access to the +status of the director (commands status and .status). +It could be a security problem if there is a bug in the ACL code of the +director. + +Concerning File and Storage Daemons' configuration:\\ +In tray-monitor.conf, the Name in the Monitor resource must point to a +Director resource in bacula-fd/sd.conf, with the Monitor directive set +to Yes (once again, see the documentation). +It could be a security problem if there is a bug in the code which check +if a command is valid for a Monitor (this is very unlikely as the code +is pretty simple). + + +\section{Sample Tray Monitor configuration} +\label{SampleConfiguration1} +\index[general]{Sample Tray Monitor configuration} + +An example Tray Monitor configuration file might be the following: + +\footnotesize +\begin{verbatim} +# +# Bacula Tray Monitor Configuration File +# +Monitor { + Name = rufus-mon # password for Directors + Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR" + RefreshInterval = 10 seconds +} + +Client { + Name = rufus-fd + Address = rufus + FDPort = 9102 # password for FileDaemon + Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn" +} +Storage { + Name = rufus-sd + Address = rufus + SDPort = 9103 # password for StorageDaemon + Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6" +} +Director { + Name = rufus-dir + DIRport = 9101 + address = rufus +} +\end{verbatim} +\normalsize + +\subsection{Sample File daemon's Director record.} +\index[general]{Sample File daemon's Director record. } +\index[general]{Record!Sample File daemon's Director } + +Click +\ilink{here to see the full example.}{SampleClientConfiguration} + + +\footnotesize +\begin{verbatim} +# +# Restricted Director, used by tray-monitor to get the +# status of the file daemon +# +Director { + Name = rufus-mon + Password = "FYpq4yyI1y562EMS35bA0J0QC0M2L3t5cZObxT3XQxgxppTn" + Monitor = yes +} +\end{verbatim} +\normalsize + +\subsection{Sample Storage daemon's Director record.} +\index[general]{Record!Sample Storage daemon's Director } +\index[general]{Sample Storage daemon's Director record. } + +Click +\ilink{here to see the full example.}{SampleConfiguration} + +\footnotesize +\begin{verbatim} +# +# Restricted Director, used by tray-monitor to get the +# status of the storage daemon +# +Director { + Name = rufus-mon + Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6" + Monitor = yes +} +\end{verbatim} +\normalsize + +\subsection{Sample Director's Console record.} +\index[general]{Record!Sample Director's Console } +\index[general]{Sample Director's Console record. } + +Click +\ilink{here to see the full +example.}{SampleDirectorConfiguration} + +\footnotesize +\begin{verbatim} +# +# Restricted console used by tray-monitor to get the status of the director +# +Console { + Name = Monitor + Password = "GN0uRo7PTUmlMbqrJ2Gr1p0fk0HQJTxwnFyE4WSST3MWZseR" + CommandACL = status, .status +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/install/quickstart.tex b/docs/manuals/fr/install/quickstart.tex new file mode 100644 index 00000000..07c045db --- /dev/null +++ b/docs/manuals/fr/install/quickstart.tex @@ -0,0 +1,415 @@ +%% +%% + +\chapter{D\'emarrer avec Bacula} +\label{_ChapterStart37} +\index[general]{Bacula!D\'emarrer avec } +\index[general]{D\'emarrer avec Bacula } + +Si vous \^etes comme moi, vous voulez faire fonctionner Bacula imm\'ediatement +pour en avoir un aper\c{c}u, puis, plus tard, vous reviendrez en arri\`ere +pour lire et conna{\^\i}tre tous les d\'etails. C'est exactement ce que ce +chapitre se propose d'accomplir : vous faire avancer rapidement sans tous les +d\'etails. Si vous voulez sauter la section sur les Pools, Volumes et Labels, +vous pourrez toujours y revenir, mais s'il vous pla\^it, veuillez lire ce +chapitre jusqu'\`a la fin, et en particulier suivre les instructions pour +tester votre lecteur de bandes. + +Nous supposons que vous \^etes parvenus \`a construire et installer Bacula, +sinon, vous devriez d'abord jeter un oeil aux +\ilink{Pr\'erequis (syst\`eme)}{SysReqs} puis au chapitre +\ilink{Compiler et installer Bacula}{_ChapterStart17} de ce manuel. + +\label{JobsandSchedules} +\section{Comprendre les Jobs et Schedules} +\index[general]{Jobs!Comprendre} +\index[general]{Schedules!Comprendre} +\addcontentsline{toc}{section}{Comprendre les Jobs et Schedules} + +Afin de rendre Bacula aussi flexible que possible, les directives lui sont +donn\'ees en plusieurs endroits. L'instruction principale est la ressource Job, +qui d\'efinit un job. Un job de type sauvegarde consiste en g\'en\'eral en un +FileSet, un client, un Schedule pour un ou plusieurs niveaux ou horaires de sauvegardes, +un Pool, ainsi que des instructions additionnelles. Un autre point de vue +est de consid\'erer le FileSet comme "Que sauvegarder ?", le Client comme +"Qui sauvegarder ?", le Schedule comme "Quand sauvegarder ?" et le Pool +comme "O\`u sauvegarder ?" (c'est \`a dire, "Sur quel volume ?) + +Typiquement, une combinaison FileSet/Client aura un job correspondant. La plupart +des directives, telles que les FileSets, Pools, Schedules, peuvent \^etre +m\'elang\'ees et partag\'ees entre les jobs. Ainsi, vous pouvez avoir deux d\'efinitions +(ressources) de jobs sauvegardant diff\'erents serveurs et utilisant les m\^emes +Schedule, FileSet (sauvegardant donc les m\^emes r\'epertoires sur les deux +machines) et peut-\^etre m\^eme les m\^emes Pools. Le Schedule d\'efinira quel +type de sauvegarde sera ex\'ecut\'e et \`a quel moment (par exemple les Full le +mercredi, les incr\'ementales le reste de la semaine), et lorsque plus d'un job +utilise le m\^eme Schedule la priorit\'e du job d\'etermine lequel d\'emarre en premier. +Si vous avez de nombreux jobs, vous devriez utiliser la directive JobDefs, +qui vous permet de d\'efinir des param\`etres par d\'efaut pour vos jobs, qui peuvent \^etre +chang\'es au sein de la ressource Job, mais qui vous \'evitent de r\'e\'ecrire les m\^emes +param\`etres pour chaque job. En plus des FileSets que vous voulez sauvegarder, +vous devriez aussi avoir un job qui sauvegarde votre catalogue. + +Enfin, sachez qu'en plus des jobs de type Backup, vous pouvez aussi utiliser +des jobs de type restore, verify, admin, qui ont chacun des exigences +diff\'erentes. + +\label{PoolsVolsLabels} + +\section{Comprendre les Pools, Volumes et Labels} +\index[general]{Comprendre les Pools, Volumes et Labels } +\index[general]{Labels!Comprendre les Pools Volumes et } +\addcontentsline{toc}{section}{Comprendre les Pools, Volumes et Labels} + +Si vous avez utilis\'e un programme tel que {\bf tar} pour sauvegarder votre +syst\`eme, les notions de Pools, Volumes et labels peuvent vous sembler un peu +confuses au premier abord. Un Volume est un simple support physique +(cartouche, ou simple fichier) sur lequel Bacula \'ecrit vos donn\'ees de +sauvegarde. Les Pools regroupent les Volumes de sorte qu'une sauvegarde n'est +pas restreinte \`a la capacit\'e d'un unique Volume. Par cons\'equent, +plut\^ot que de nommer explicitement les Volumes dans votre Job, vous +sp\'ecifiez un Pool, et Bacula se chargera de s\'electionner le prochain +Volume utilisable du Pool et vous demandera de le monter. + +Bien que les options de base soient sp\'ecifi\'ees dans la ressource Pool du +fichier de configuration du Director, le Pool {\bf r\'eel} est g\'er\'e par le +Catalogue Bacula. Il contient les informations de la ressource Pool +(bacula-dir.conf) ainsi que les informations concernant tous les Volumes qui +ont \'et\'e ajout\'es au Pool. L'ajout de Volumes se fait en principe +manuellement depuis la Console gr\^ace \`a la commande {\bf label}. + +Pour chaque Volume, Bacula g\`ere une quantit\'e d'informations consid\'erable +telles que les premi\`ere et derni\`ere date et heure d'\'ecriture, le nombre +de fichiers sur le Volume, le nombre de bytes sur le Volume, le nombre de +montages, etc. + +Pour que Bacula puisse lire ou \'ecrire sur un Volume physique, celui-ci doit +avoir re\c{c}u un \'etiquettage logiciel afin que Bacula soit assur\'e que le +bon Volume est mont\'e. Ceci s'effectue en principe manuellement depuis la +Console gr\^ace \`a la commande {\bf label}. + +Les \'etapes de cr\'eation de Pool, ajout de Volumes \`a ce Pool, et +\'ecriture d'\'etiquettes logicielles sur les Volumes, peuvent sembler +p\'enibles au premier abord, mais en fait, elles sont tout \`a fait simples +\`a franchir, et elles vous permettent d'utiliser plusieurs Volumes (plut\^ot +que d'\^etre limit\'e \`a la capacit\'e d'un seul). Les Pools vous procurent +aussi une flexibilit\'e importante pour votre politique de sauvegarde. Par +exemple, vous pouvez avoir un Pool de Volumes "Daily" pour vos sauvegardes +Incr\'ementales et un Pool de Volumes "Weekly" pour vos sauvegardes +compl\`etes (Full). En sp\'ecifiant le Pool appropri\'e dans les Jobs de +sauvegarde quotidiens et hebdomadaires, vous garantissez qu'aucun Job +quotidien n'\'ecrira jamais sur un Volume du Pool r\'eserv\'e aux sauvegardes +hebdomadaire et vice versa, et Bacula vous dira quelle cartouche est requise, +et quand. + +Pour plus de d\'etails concernant les Pools, consultez la section +\ilink{Ressource Pool}{PoolResource} du chapitre sur la +configuration du Director, ou poursuivez votre lecture, nous reviendrons plus +tard sur ce sujet. + +\section{Param\'etrage des fichiers de configuration de Bacula} +\label{config} +\index[general]{Param\'etrage des fichiers de configuration de Bacula } +\index[general]{Bacula!Param\'etrage des fichiers de configuration de } +\addcontentsline{toc}{section}{Param\'etrage des fichiers de configuration +de Bacula} + +Apr\`es avoir ex\'ecut\'e la commande {\bf ./configure} {\it ad hoc}, {\bf +make} et {\bf make install}, si c'est la premi\`ere fois que vous ex\'ecutez +Bacula, vous devez cr\'eer des fichiers de configuration valides pour le +Director, le File Daemon, le Storage Daemon et le programme Console. Si vous +avez suivi nos recommandations, des fichiers de configuration par d\'efaut +ainsi que les binaires des {\it daemons} seront situ\'es dans votre +r\'epertoire d'installation. Dans tous les cas les binaires se trouvent dans +le r\'epertoire que vous avez sp\'ecifi\'e au niveau de l'option {\bf +\verb{--{sbindir} de la commande {\bf ./configure}, et les fichiers de configuration +se trouvent dans le r\'epertoire que vous avez sp\'ecifi\'e au niveau de +l'option {\bf \verb{--{sysconfdir}. + +Lors des param\'etrages initiaux de Bacula, il vous faudra investir un peu de +temps pour modifier les fichiers de configuration par d\'efaut afin de +les adapter \`a votre environnement. Ceci peut n\'ecessiter de red\'emarrer +Bacula plusieurs fois jusqu'\`a ce que tout fonctionne correctement. Ne +c\'edez pas au d\'esespoir. Une fois que vous aurez cr\'e\'e vos fichiers de +configuration, vous n'aurez que rarement besoin de les changer et de +red\'emarrer Bacula. Le gros du travail consistera \`a changer la cartouche +quand elle est pleine. + +\subsection{ +\ilink{Configurer le programme Console}{_ChapterStart36}} +\index[general]{Console!Configurer le programme } +\index[general]{Configurer le programme Console } +\addcontentsline{toc}{subsection}{Configurer le programme Console} + +Le programme console est utilis\'e par l'administrateur pour interagir avec le +Director et pour arr\^eter et d\'emarrer manuellement des jobs, ou encore pour +obtenir des informations sur les jobs en cours d'ex\'ecution ou programm\'es. + +Le fichier de configuration de la Console se trouve dans le r\'epertoire que +vous avez sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande +{\bf ./configure} et par d\'efaut se nomme {\bf console.conf}. + +Si vous avez choisi de construire la Console GNOME avec l'option {\bf +\verb{--{enable-gnome}, vous y trouverez \'egalement son fichier de configuration par +d\'efaut, nomm\'e {\bf gnome-console.conf}. + +Il en va de m\^eme pour la console wxWidgets, qui est construite par l'option +{\bf \verb{--{enable-bwx-console}, et le nom du fichier de configuration par d\'efaut +est, dans ce cas, {\bf bwx-console.conf}. + +Normalement, pour les nouveaux +utilisateurs, aucune modification n'est requise pour ces fichiers. Les +r\'eglages par d\'efaut sont raisonnables. + +\subsection{ +\ilink{Configurer le programme Monitor}{_ChapterStart35}} +\index[general]{Monitor!Configurer le programme } +\index[general]{Configurer le programme Monitor } +\addcontentsline{toc}{subsection}{Configurer le programme Monitor} + +Le programme Monitor est typiquement une ic\^one dans la barre des t\^aches. +Cependant, lorsque l'ic\^one est \'etendue en une fen\`etre, l'administrateur ou +l'utilisateur peut obtenir des informations concernant le Director ou l'\'etat +des sauvegardes sur la machine locale ou n'importe quelle autre {\it daemon} +Bacula configur\'e. + +\includegraphics{./Bacula-tray-monitor.eps} + +L'image montre le tray-monitor configur\'e pour trois {\it daemons}. En +cliquant sur les boutons radio dans le coin en haut \`a gauche de l'image, +vous pouvez voir l'\'etat de chacun des {\it daemons}. L'image montre l'\'etat +du Storage Daemon (MainSD) s\'electionn\'e. + +Le fichier de configuration du Monitor se trouve dans le r\'epertoire +sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande {\bf +./configure} et se nomme par d\'efaut {\bf tray-monitor.conf}. En principe, +pour les nouveaux utilisateurs, il suffit de changer les permissions de ce +fichier pour permettre aux utilisateurs non-root d'ex\'ecuter le Monitor, en +effet cette application doit \^etre ex\'ecut\'e par le m\^eme utilisateur que +l'environnement graphique (n'oubliez pas de donner aux non-root le droit +d'ex\'ecuter {\bf bacula-tray-monitor}). Ceci ne constitue pas une faille de +s\'ecurit\'e tant que vous utilisez les r\'eglages par d\'efaut. + +\subsection{ +\ilink{Configurer le File Daemon}{_ChapterStart25}} +\index[general]{Configurer le File Daemon } +\index[general]{Daemon!Configurer le File } +\addcontentsline{toc}{subsection}{Configurer le File Daemon} + +Le File Daemon, est le programme qui s'ex\'ecute sur chaque machine cliente. A +la demande du Director, il d\'etermine les fichiers \`a sauvegarder et les +exp\'edie au Storage Daemon. + +Le fichier de configuration du File Daemon se trouve dans le r\'epertoire +sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande {\bf +./configure} et se nomme par d\'efaut {\bf bacula-fd.conf}. Normalement, pour +les nouveaux utilisateurs, aucune modification n'est requise pour ce fichier. +Les r\'eglages par d\'efaut sont raisonnables. Cependant, si vous envisagez de +sauvegarder plus d'une machine, il vous faudra installer le File Daemon avec +un fichier de configuration sp\'ecifique sur chaque machine \`a sauvegarder. +Les informations concernant chaque File Daemon doivent appara{\^\i}tre dans le +fichier de configuration du Director. + +\subsection{ +\ilink{Configurer le Director}{_ChapterStart40}} +\index[general]{Director!Configurer le } +\index[general]{Configurer le Director } +\addcontentsline{toc}{subsection}{Configurer le Director} + +Le director est le programme central qui contr\^ole tous les autres {\it +daemons}. Il planifie et surveille les jobs \`a ex\'ecuter. + +Le fichier de configuration du Director se trouve dans le r\'epertoire +sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande {\bf +./configure} et se nomme par d\'efaut {\bf bacula-dir.conf}. + +En g\'en\'eral, la seule modification n\'ecessaire consiste \`a faire en sorte +que la directive {\bf Include} de la Ressource FileSet contienne au moins une +ligne avec un nom de fichier ou de r\'epertoire valide \`a sauvegarder. + +Si vous ne poss\'edez pas de lecteur DLT, vous voudrez probablement modifier +la ressource Storage pour donner un nom plus repr\'esentatif de votre +p\'eriph\'erique de stockage. Vous pouvez toujours utiliser les noms existants +puisque vous \^etes libre de les assigner arbitrairement, mais ils doivent +s'accorder avec les noms correspondants dans le fichier de configuration du +Storage Daemon. + +Vous pouvez aussi changer l'adresse \'electronique pour les notifications vers +votre propre adresse e-mail plut\^ot que vers celle de {\bf root} +(configuration par d\'efaut). + +Enfin, si vous avez plusieurs syst\`emes \`a sauvegarder, il vous faudra +sp\'ecifier un File Daemon (ou client) pour chaque syst\`eme sauvegard\'e, +pr\'ecisant ses nom, adresse et mot de passe. Nous estimons que baptiser vos +{\it daemons} du nom de vos syst\`emes suffix\'es avec {\bf -fd} aide beaucoup +\`a corriger les erreurs. Ainsi, si votre syst\`eme est {\bf foobaz}, vous +nommerez le {\it daemon} {\bf foobaz-fd}. Pour le Director, vous pourriez +utiliser {\bf foobaz-dir}, et {\bf foobaz-sd} pour le Storage Daemon. +Chacun de vos composants de Bacula {\bf doit} avoir un nom unique +Si vous les nommez tous \`a l'identique, en plus de ne jamais savoir +quel {\it daemon} envoie quel message, s'ils partagent le m\^eme r\'epertoire +de travail (working directory), les noms de fichiers temporaires des {\it daemons} +ne seront pas uniques et vous aurez d'\'etranges erreurs. + +\subsection{ +\ilink{Configurer le Storage Daemon}{_ChapterStart31}} +\index[general]{Daemon!Configurer le Storage } +\index[general]{Configurer le Storage Daemon } +\addcontentsline{toc}{subsection}{Configurer le Storage Daemon} + +Le Storage Daemon est responsable, sur demande du Director, de la r\'eception +des donn\'ees en provenance des File Daemons, et de leur \'ecriture sur le +medium de stockage, ou, dans le cas d'une restauration, de trouver les +donn\'ees pour les envoyer vers le File Daemon. + +Le fichier de configuration du Storage Daemon se trouve dans le r\'epertoire +sp\'ecifi\'e au niveau de l'option {\bf \verb{--{sysconfdir} de la commande {\bf +./configure} et se nomme par d\'efaut {\bf bacula-sd.conf}. Modifiez ce +fichier pour accorder les noms de p\'eriph\'eriques de stockage \`a ceux que +vous poss\'edez. Si le processus d'installation a convenablement d\'etect\'e +votre syst\`eme, elles seront d\'ej\`a correctement r\'egl\'ees. Ces +ressources de stockage "Name" et "Media Type" doivent \^etre les m\^emes +que leurs correspondantes du fichier de configuration du Director {\bf +bacula-dir.conf}. Si vous souhaitez sauvegarder vers un fichier plut\^ot que +sur des bandes, la ressource Device doit pointer vers un r\'epertoire o\`u des +fichiers seront cr\'e\'es en guise de Volumes lorque vous \'etiquetterez +(label) vos Volumes. +\label{ConfigTesting} + +\section{Tester vos Fichiers de Configuration} +\index[general]{Configuration!Tester vos Fichiers de } +\index[general]{Tester vos Fichiers de Configuration } +\addcontentsline{toc}{section}{Tester vos Fichiers de Configuration} + +Vous pouvez tester la validit\'e syntaxique de vos fichiers de configuration, +afficher tout message d'erreur et terminer. Par exemple, en supposant que vous +avez install\'e vos binaires et fichiers de configuration dans le m\^eme +r\'epertoire, + +\footnotesize +\begin{verbatim} +cd +./bacula-dir -t -c bacula-dir.conf +./bacula-fd -t -c bacula-fd.conf +./bacula-sd -t -c bacula-sd.conf +./bconsole -t -c bconsole.conf +./gnome-console -t -c gnome-console.conf +./bwx-console -t -c wx-console.conf +su -c "./bacula-tray-monitor -t -c tray-monitor.conf" +\end{verbatim} +\normalsize + +testera le fichier de configuration de chacun des principaux programmes. Si le +fichier de configuration est correct, le programme se termine +sans rien afficher. Veuillez noter que selon les options de configuration que +vous avez choisies, il se peut qu'aucune des commandes ci-dessus ne soit +valable sur votre syst\`eme. Si vous avez install\'e les binaires dans les +r\'epertoires traditionnels d'Unix plut\^ot que dans un simple r\'epertoire, +il vous faudra modifier les commandes ci-dessus en cons\'equence (pas de +"./" devant les commandes, et un chemin devant les fichiers de +configuration). +\label{TapeTesting} + +\section{Tester la compatibilit\'e de Bacula avec votre lecteur de bandes} +\index[general]{Tester la compatibilit\'e de Bacula avec votre lecteur de +bandes } +\index[general]{Bandes!Tester la compatibilit\'e de Bacula avec votre lecteur +de } +\addcontentsline{toc}{section}{Tester la compatibilit\'e de Bacula avec +votre lecteur de bandes} + +Avant de gaspiller votre temps avec Bacula pour finalement constater qu'il ne +fonctionne pas avec votre lecteur de bandes, veuillez s'il vous pla\^it lire le +chapitre +\ilink{btape -- Tester votre lecteur de bandes}{_ChapterStart27} +de ce manuel. Si vous poss\'edez un lecteur standard SCSI moderne sur un Linux +ou un Solaris, fort probablement, il fonctionnera, mais mieux vaut tester que +d'\^etre d\'e\c{c}u. Pour FreeBSD (et probablement les autres xBSD), la +lecture du chapitre mentionn\'e ci-dessus est un devoir. Pour FreeBSD, +consultez aussi +\elink{The FreeBSD Diary}{http://www.freebsddiary.org/bacula.php} pour une +description d\'etaill\'ee de la m\'ethode pour faire fonctionner Bacula sur +votre syst\`eme. De plus, les utilisateurs de versions de FreeBSD +ant\'erieures \`a 4.9-STABLE dat\'ee du lundi 29 d\'ecembre 2003 15:18:01 UTC +qui pr\'evoient d'utiliser des lecteurs de bandes sont invit\'es \`a lire le +fichier {\bf platforms/freebsd/pthreads-fix.txt} du r\'epertoire principal de +Bacula, qui contient d'importantes informations sur la compatibilit\'e de +Bacula avec leur syst\`eme. +\label{notls} + +\section{D\'ebarrassez-vous du r\'epertoire /lib/tls} +\index[general]{D\'ebarrassez-vous du r\'epertoire /lib/tls } +\addcontentsline{toc}{section}{D\'ebarrassez-vous du r\'epertoire /lib/tls} + +La nouvelle librairie pthreads {\bf /lib/tls} install\'ee par d\'efaut sur les +syst\`emes Red Hat r\'ecents (kernels 2.4.x) est d\'efectueuse. Vous devez la +supprimer ou la renommer, puis rebooter votre syst\`eme avant d'ex\'ecuter +Bacula, faute de quoi, apr\`es environ une semaine de fonctionnement, Bacula +se bloquera pour de longues p\'eriodes, voire d\'efinitivement. Veuillez consulter +le chapitre \ilink{Syst\`emes support\'es}{SupportedOSes} pour plus +d'informations sur ce probl\`eme. + +Ce probl\`eme n'existe plus avec les noyaux 2.6. + +\label{Running1} + +\section{Ex\'ecuter Bacula} +\index[general]{Bacula!Ex\'ecuter } +\index[general]{Ex\'ecuter Bacula } +\addcontentsline{toc}{section}{Ex\'ecuter Bacula} + +La partie la plus importante de l'ex\'ecution de Bacula est probablement la +capacit\'e de restaurer les fichiers. Si vous n'avez pas essay\'e de +r\'ecup\'erer des fichiers au moins une fois, vous subirez une bien plus forte +pression le jour o\`u vous devrez r\'eellement le faire, et serez enclin \`a +commettre des erreurs que vous n'auriez pas commises si vous aviez d\'ej\`a +essay\'e. + +Pour avoir rapidement une bonne id\'ee de la fa\c{c}on d'utiliser Bacula, +nous vous recommandons {\bf fortement} de suivre les exemples du +\ilink{chapitre ex\'ecuter Bacula}{_ChapterStart1} de ce manuel, +o\`u vous trouverez des informations d\'etaill\'ees sur l'ex\'ecution de +Bacula. + +\section{Rotation des logs} +\index[general]{Logs!Rotation des } +\index[general]{Rotation des logs } +\addcontentsline{toc}{section}{Rotation des logs} + +Si vous utilisez le {\bf bacula-dir.conf} par d\'efaut ou une variante, vous +constaterez qu'il r\'ecup\`ere toutes les sorties de Bacula dans un fichier. +Pour \'eviter que ce fichier ne croisse sans limites, nous vous recommandons +de copier le fichier {\bf logrotate} depuis {\bf scripts/logrotate} vers {\bf +/etc/logrotate.d/bacula}. Ainsi les fichiers de logs subiront une rotation +mensuelle et seront conserv\'es pour une dur\'ee maximum de cinq mois. Vous +pouvez \'editer ce fichier pour adapter la rotation \`a votre convenance. + +\section{Log Watch} +\index[general]{Watch!Log} +\index[general]{Log Watch} +\addcontentsline{toc}{section}{Log Watch} +Certains syst\`emes tels que RedHat et Fedora ex\'ecutent le programme +logwatch chaque nuit pour analyser vos fichiers de log et vous +envoyer un rapport par mail. Si vous souhaitez inclure la sortie +de vos jobs Bacula dans ce rapport, veuillez regarder dans le r\'epertoire +{\bf scripts/logwatch}. Le fichier {\bf README} fournit une br\`eve +explication sur la fa\c {c}on d'installer le script, et quelle genre +de r\'esultats en attendre. + +\section{Reprise d'activit\'e apr\`es un d\'esastre (disaster recovery)} +\index[general]{Recovery!Reprise d'activit\'e apr\`es un d\'esastre disaster } +\index[general]{Reprise d'activit\'e apr\`es un d\'esastre (disaster recovery) +} +\addcontentsline{toc}{section}{Reprise d'activit\'e apr\`es un d\'esastre +(disaster recovery)} + +Si vous avez l'intention d'utiliser Bacula en tant qu'outil de disaster +recovery plut\^ot que comme un simple programme pour restaurer les fichiers +perdus, vous serez int\'eress\'e par le +\ilink{chapitre Plan de reprise d'activit\'e avec +Bacula}{_ChapterStart38} de ce manuel. + +De toute fa\c{c}on, vous \^etes fortement invit\'e \`a tester soigneusement +la restauration de quelques fichiers que vous aurez pr\'ealablement +sauvegard\'es, plut\^ot que d'attendre qu'un d\'esastre ne frappe. Ainsi, vous +serez pr\'epar\'e. diff --git a/docs/manuals/fr/install/security.tex b/docs/manuals/fr/install/security.tex new file mode 100644 index 00000000..c800ffc7 --- /dev/null +++ b/docs/manuals/fr/install/security.tex @@ -0,0 +1,336 @@ +%% +%% + +\chapter{Consid\'erations sur la s\'ecurit\'e de Bacula} +\label{_ChapterStart14} +\index[general]{Bacula!Consid\'erations sur la s\'ecurit\'e de} +\index[general]{Consid\'erations sur la s\'ecurit\'e de Bacula} +\index[general]{S\'ecurit\'e} + +\begin{itemize} +\item La s\'ecurit\'e, c'est de pouvoir restaurer vos fichiers, aussi, lisez + attentivement le chapitre \ilink{Critical Items Chapter}{Critical} de + ce manuel. +\item Le client ({\bf bacula-fd}) doit \^etre ex\'ecut\'e en tant que root + afin d'avoir l'acc\`es \`a tous les fichiers du syst\`eme. +\item Il n'est pas n\'ecessaire d'ex\'ecuter le Director en tant que root. +\item Il n'est pas n\'ecessaire d'ex\'ecuter le Storage Daemon en tant que + root, mais vous devez vous assurer qu'l peut utiliser le lecteur de bandes, + dont l'acc\`es est presque toujours r\'eserv\'e \`a root par d\'efaut. + De plus, si vous n'ex\'ecutez pas le Storage Daemon en tant que root, il sera + dans l'incapacit\'e de r\'egler automatiquement les param\`etres de votre lecteur + de bandes. En effet, ces fonctions requi\`erent les droits root sur la plupart + des syst\`emes d'exploitation. +\item Vous devriez restreindre l'acc\`es au fichiers de configuration de + Bacula, de sorte que les mots de passe ne soient pas lisibles par tous. Les + {\it daemons} {\bf Bacula} sont prot\'eg\'es par des mots de passe et CRAM-MD5 +(i.e. les mots de passe ne sont pas envoy\'es sur le r\'eseau). Ceci assure +que tout le monde ne peut acc\'eder aux {\it daemons}. C'est une protection +raisonnablement bonne, mais qui peut \^etre craqu\'ee par un expert. +\item Si vous utilisez les ports recommand\'es 9101,9102 et 9103, vous voudrez + probablement prot\'eger ces ports des acc\`es externes \`a l'aide d'un + firewall et/ou en utilisant tcp wrappers ({\bf etc/hosts.allow}). +\item Actuellement, toutes les donn\'ees sont envoy\'ees sur le r\'eseau sans + chiffrement. Par cons\'equent, \`a moins que vous n'utilisiez {\bf ssh} ou {\bf + stunnel} pour la transmission de port (NDT: port forwarding), il n'est pas +recommand\'e de faire des sauvegardes \`a travers un r\'eseau non +s\'ecuris\'e (par exemple, Internet). Nous pr\'evoyons d'int\'egrer le +chiffrage {\bf ssl} dans une version future. +\item Vous devriez vous assurer que seuls les {\it daemons} de Bacula ont + acc\`es en lecture et \'ecriture aux r\'epertoires de travail de Bacula. +\item Si vous utilisez {\bf MySQL}, il n'est pas n\'ecessaire de l'ex\'ecuter + en tant que root +\item Le script par d\'efaut de Bacula {\bf grant-mysql-permissions} accorde + toutes les permissions d'utilisation de la base de donn\'ees MySQL sans mot + de passe. Si vous voulez la s\'ecurit\'e, affinez ceci ! +\item N'oubliez pas que Bacula est un programme r\'eseau, ainsi quiconque sur + le r\'eseau dispose du programme console et du mot de passe du Director peut + acc\'eder \`a Bacula et aux donn\'ees sauvegard\'ees. +\item Vous pouvez restreindre les adresses IP avec auxquelles Bacula se + connectera en utilisant les enregistrements appropri\'es {\bf DirAddress}, + {\bf FDAddress}, ou {\bf SDAddress} dans les fichiers de configurations +respectifs des {\it daemons} +\item Soyez conscient que si vous sauvegardez votre catalogue avec le script + par d\'efaut, et si l'acc\`es \`a votre catalogue est prot\'eg\'e par un mot de passe, + ce dernier est transmis en tant qu'option de ligne de commande \`a ce script, + ce qui le rend visible \`a tout utilisateur du syst\`eme. Si vous voulez + s\'ecuriser ce point, vous devez le passer via une variable d'environnement + ou un fichier s\'ecuris\'e. +\end{itemize} + +\section{Compatibilit\'e ascendante} +\index[general]{Compatibilit\'e ascendante} +\addcontentsline{toc}{section}{Compatibilit\'e ascendante} +L'un des principaux objectifs de Bacula est de garantir que vous pouvez +restaurer depuis des cartouches (ou depuis des volumes disque) \'ecrites des ann\'ees +auparavant. Ceci implique que chaque nouvelle version de Bacula devrait \^etre +capable de relire les anciens formats de cartouches. Le premier probl\`eme est de +s'assurer que le mat\'eriel fonctionne encore malgr\'e les ann\'ees, et que les supports +sont encore valides. Ensuite, votre syst\`eme d'exploitation doit \^etre capable +de s'interfacer avec le p\'eriph\'erique et finalement, Bacula doit \^etre capable +de reconna\^itre les anciens formats. De tous ces probl\`emes, nous ne pouvons +prendre en charge que le dernier, pour les autres, vous devez vous pr\'eparer +consciencieusement. + +Depuis les tous premiers stades de Bacula (janvier 2000) jusqu'\`a aujourd'hui +(D\'ecembre 2005), Bacula a connu deux formats majeurs d'\'ecriture sur les +cartouches. Le second format a \'et\'e introduit dans la version 1.27 en +novembre 2002, et n'a pas chang\'e depuis. En principe, Bacula devrait encore pouvoir +lire le format d'origine, mais j'avoue ne pas avoir essay\'e depuis longtemps... + +Bien que le format des cartouches soit fix\'e, les types de donn\'ees qui peuvent \^etre +\'ecrites sur les cartouches sont extensibles, ce qui nous a permis d'ajouter de +nouvelles fonctionnalit\'es telles que les ACLs, les donn\'ees Win32, les donn\'ees +chiffr\'ees... Naturellement, une ancienne version de Bacula ne saurait lire des +nouveaux flux de donn\'ees, mais chaque nouvelle version de Bacula est en principe +capable de lire les anciens flux. + +Si vous voulez \^etre absolument certain de pouvoir lire vos vieilles cartouches, +vous devriez : + +1. Essayer de lire les vieilles cartouches de temps en temps, une fois par an +par exemple. + +2. Conserver une copie statiquement li\'ee de chaque version de Bacula que vous +avez utilis\'ee en production. Ainsi, si pour quelque raison nous venions \`a +abandonner la compatibilit\'e avec les anciens formats de cartouches, vous pourriez +toujours remettre en service une vieille copie de Bacula... + +Le second point est probablement excessif, en toute rigueur, il pourrait vous +sauver un jour. + +\label{wrappers} + +\section{Configurer et tester TCP Wrappers} +\index[general]{Configurer et tester TCP Wrappers} +\index[general]{Bacula!Configurer et tester TCP Wrappers} +\index[general]{TCP Wrappers} +\index[general]{Wrappers!TCP} +\index[general]{libwrappers} +\addcontentsline{toc}{section}{Configurer et tester TCP Wrappers} + +Les TCP Wrappers sont impl\'ement\'es si vous les activez lors de la +configuration ({\bf ./configure \verb{:--:{with-tcp-wrappers}). Avec ce code activ\'e, vous +pourrez contr\^oler qui peut acc\'eder \`a vos {\it daemons}. Ce contr\^ole +est obtenu par la modification du fichier {\bf /etc/hosts.allow}. Le nom de +programme qu'utilise {\bf Bacula} pour appliquer ces restrictions est celui +que vous avez sp\'ecifi\'e dans le fichier de configuration du {\it daemon}. +Vous ne devez pas utiliser l'option {\bf twist} dans votre {\bf +/etc/hosts.allow} car elle stopperait les {\it daemons} Bacula lorsqu'une +connection est refus\'ee. + +Le nom exact du paquet requis pour compiler avec le support TCP wrappers +d\'epend du syst\`eme. Il s'agit, par exemple, de tcpd-devel sur SuSE, et de +tcp\_wrappers sur RedHat. + +Dan Langille a fourni les informations suivantes concernant la configuration +et les tests de TCP Wrappers avec Bacula. + +Si vous lisez hosts\_options(5), vous verrez une option nomm\'ee twist. Cette +option remplace le processus courant par une instance de la commande shell +sp\'ecifi\'ee. Voici un exemple typique de son utilisation : + +\footnotesize +\begin{verbatim} +ALL : ALL \ + : severity auth.info \ + : twist /bin/echo "Vous n'\^etes pas autoris\'e \`a utiliser %d depuis %h." +\end{verbatim} +\normalsize + +\label{question-1} +Le code libwrap tente d'\'eviter {\bf twist} s'il est +ex\'ecut\'e dans un processus r\'esident. Il en r\'esulte que le processus (e.g. +bacula-fd, bacula-sd, bacula-dir) sera stopp\'e si la premi\`ere connection +\`a son port provoque l'invocation de l'option twist. Le risque est qu'une +attaque provoque l'arr\^et des {\it daemons}. Cette situation est \'evit\'ee si votre +fichier /etc/hosts.allow contient un jeu de r\`egles appropri\'e. L'exemple +suivant est suffisant : + +\footnotesize +\begin{verbatim} +undef-fd : localhost : allow +undef-sd : localhost : allow +undef-dir : localhost : allow +undef-fd : ALL : deny +undef-sd : ALL : deny +undef-dir : ALL : deny +\end{verbatim} +\normalsize + +Vous devez accorder les noms des {\it daemons} \`a ceux sp\'ecifi\'es dans leurs +fichiers de configuration respectifs. Ce ne sont, en g\'en\'eral, pas les noms +des fichiers binaires des {\it daemons}. Il n'est pas possible d'utiliser +les noms des binaires car plusieurs {\it daemons} peuvent \^etre ex\'ecut\'es +sur une machine avec des fichiers de configuration distincts. + +Dans ces exemples, le Director est undef-dir, le +Storage Daemon est undef-sd, et le File Daemon est undef-fd. Ajustez ces noms pour +qu'ils conviennent \`a votre configuration. L'exemple de r\`egles ci-dessus suppose que +SD, FD et DIR sont tous sur la m\^eme machine. Si vous avez un client FD +distant, il vous suffira de placer le jeu de r\`egles suivant sur ce client : + +\footnotesize +\begin{verbatim} +undef-fd : director.example.org : allow +undef-fd : ALL : deny +\end{verbatim} +\normalsize + +O\`u director.example.org est l'h\^ote qui contactera le client (i.e. la +machine sur laquelle le Bacula Director tourne). L'usage de "ALL : deny" +assure que l'option twist (si pr\'esente) n'est pas invoqu\'ee. Pour tester +correctement votre configuration, d\'emarrez le(s) {\it daemon(s)}, puis +essayez de vous y connecter depuis une adresse IP qui devrait \^etre capable +de le faire. Vous devriez voir quelque chose comme : + +\footnotesize +\begin{verbatim} +$ telnet undef 9103 +Trying 192.168.0.56... +Connected to undef.example.org. +Escape character is '^]'. +Connection closed by foreign host. +$ +\end{verbatim} +\normalsize + +C'est la r\'eponse correcte. Si vous voyez ceci : + +\footnotesize +\begin{verbatim} +$ telnet undef 9103 +Trying 192.168.0.56... +Connected to undef.example.org. +Escape character is '^]'. +You are not welcome to use undef-sd from xeon.example.org. +Connection closed by foreign host. +$ +\end{verbatim} +\normalsize + +Alors, twist a \'et\'e invoqu\'ee, et votre configuration est incorrecte. vous +devez ajouter la directive "deny". Il est important de noter que vos tests +doivent inclure le red\'emarrage des {\it daemons} apr\`es chaque tentative de +connexion. Vous pouvez aussi tcpdchk(8) et tcpdmatch(8) pour valider jeu de +r\`egles /etc/hosts.allow. Voici un test simple avec tcpdmatch : + +\footnotesize +\begin{verbatim} +$ tcpdmatch undef-dir xeon.example.org +warning: undef-dir: no such process name in /etc/inetd.conf +client: hostname xeon.example.org +client: address 192.168.0.18 +server: process undef-dir +matched: /etc/hosts.allow line 40 +option: allow +access: granted +\end{verbatim} +\normalsize + +Si vous ex\'ecutez Bacula en tant que {\it standalone daemon}, les +avertissements ci-dessus peuvent \^etre ignor\'es sans scrupules. Voici un +exemple qui r\'ev\`ele que "deny" fait defaut \`a vos r\`egles, et que +l'option twist a \'et\'e invoqu\'ee. + +\footnotesize +\begin{verbatim} +$ tcpdmatch undef-dir 10.0.0.1 +warning: undef-dir: no such process name in /etc/inetd.conf +client: address 10.0.0.1 +server: process undef-dir +matched: /etc/hosts.allow line 91 +option: severity auth.info +option: twist /bin/echo "You are not welcome to use + undef-dir from 10.0.0.1." +access: delegated +\end{verbatim} +\normalsize + +\section{Ex\'ecuter Bacula sans \^etre root} +\index[general]{Root!Ex\'ecuter Bacula sans \^etre } +\index[general]{Ex\'ecuter Bacula sans \^etre root } +\addcontentsline{toc}{section}{Ex\'ecuter Bacula sans \^etre root} + +Voici quelques recommandations de Dan Languille : + +C'est une bonne id\'ee d'ex\'ecuter vos {\it daemons} avec des privil\`eges +aussi faibles que possible. En d'autres termes, si vous pouvez, n'ex\'ecutez +pas d'applications en tant que root si elle n'ont pas besoin d'\^etre +ex\'ecut\'ees en tant que root. Le Storage Daemon et le Director Daemon n'ont +pas besoin d'\^etre ex\'ecut\'es en tant que root. Le File Daemon en a besoin +pour acc\'eder \`a l'ensemble des fichiers du syst\`eme. Pour vous passer des +privil\`eges root, il vous faut cr\'eer un utilisateur et un groupe. Choisir +{\tt bacula} pour l'un et l'autre me semble une bonne id\'ee. + +Le port FreeBSD cr\'ee cet utilisateur et ce groupe pour vous. (En fait, au +moment ou j'\'ecris ces lignes, ce n'est pas encore le cas, mais \c{c}a le +sera bient\^ot). Voici \`a quoi ressemblent ces entr\'ees sur mon portable +FreeBSD : + +\footnotesize +\begin{verbatim} +bacula:*:1002:1002::0:0:Bacul Daemon:/var/db/bacula:/sbin/nologin +\end{verbatim} +\normalsize + +J'ai utilis\'e vipw pour cr\'eer ces entr\'ees. J'ai utilis\'e un User ID et +un Group ID disponibles sur mon syst\`eme : 1002. + +J'ai aussi cr\'e\'e un groupe dans /etc/group: + +\footnotesize +\begin{verbatim} +bacula:*:1002: +\end{verbatim} +\normalsize + +L'utilisateur bacula, contrairement au {\it daemon} Bacula, aura un +r\'epertoire d\'edi\'e (home directory) : {\tt /var/db/bacula} qui est le +r\'epertoire standard pour le catalogue de Bacula. + +A pr\'esent, vous avez un utilisateur et un groupe bacula, et vous pouvez +s\'ecuriser le r\'epertoire d\'edi\'e de bacula en utilisant cette commande : + +\footnotesize +\begin{verbatim} +chown -R bacula:bacula /var/db/bacula/ +\end{verbatim} +\normalsize + +Celle-ci assure que seul l'utilisateur bacula peut acc\'eder \`a ce +r\'epertoire. Elle signifie aussi que si nous ex\'ecutons le Director et le +Storage Daemon en tant que bacula, ces {\it daemons} auront aussi des acc\`es +restreints. Ce ne serait pas le cas s'ils \'etaient ex\'ecut\'es en tant que +root. + +Il est important de noter que le Storage Daemon a vraiment besoin +d'appartenir au groupe operator pour un acc\`es normal aux lecteurs de bandes. +(au moins sur FreeBSD, c'est ainsi que les choses sont configur\'ees par +d\'efaut). De tels p\'eriph\'eriques sont en principe attribu\'es \`a +root:operator. Il est plus facile et moins dangereux de faire de bacula un +membre de ce groupe que de jouer avec les permissions du syst\`eme. + +D\'emarrer les {\it daemons} bacula + +Pour d\'emarrer les {\it daemons} bacula sur FreeBSD, utilisez la commande : + +\footnotesize +\begin{verbatim} +/usr/local/etc/rc.d/bacula.sh start +\end{verbatim} +\normalsize + +Pour vous assurer que tous fonctionnent : + +\footnotesize +\begin{verbatim} +$ ps auwx | grep bacula +root\ 63416\ 0.0\ 0.3\ 2040 1172\ ??\ Ss\ 4:09PM 0:00.01 + /usr/local/sbin/bacula-sd -v -c /usr/local/etc/bacula-sd.conf +root\ 63418\ 0.0\ 0.3\ 1856 1036\ ??\ Ss\ 4:09PM 0:00.00 + /usr/local/sbin/bacula-fd -v -c /usr/local/etc/bacula-fd.conf +root\ 63422\ 0.0\ 0.4\ 2360 1440\ ??\ Ss\ 4:09PM 0:00.00 + /usr/local/sbin/bacula-dir -v -c /usr/local/etc/bacula-dir.conf +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/install/setup.sm b/docs/manuals/fr/install/setup.sm new file mode 100644 index 00000000..7c88dc61 --- /dev/null +++ b/docs/manuals/fr/install/setup.sm @@ -0,0 +1,23 @@ +/* + * html2latex + */ + +available { + sun4_sunos.4 + sun4_solaris.2 + rs_aix.3 + rs_aix.4 + sgi_irix +} + +description { + From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX +} + +install { + bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex + bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag + bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag + bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag + man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1 +} diff --git a/docs/manuals/fr/install/storedconf.tex b/docs/manuals/fr/install/storedconf.tex new file mode 100644 index 00000000..3bd46486 --- /dev/null +++ b/docs/manuals/fr/install/storedconf.tex @@ -0,0 +1,1269 @@ +%% +%% + +\chapter{Configuration du Storage Daemon} +\label{_ChapterStart31} +\index[general]{Configuration du Storage Daemon} +\index[general]{Configuration!Storage Daemon} + +\section{General} +\index[general]{General} +\addcontentsline{toc}{section}{General} +Le fichier de configuration du Storage Daemon a relativement peu de d\'efinitions +de resources. Cependant, en raison du nombre pl\'ethorique de media et de syst\`emes, +il doit \^etre hautement param\'etrable. Par cons\'equent, il existe un nombre assez important +de directives dans la d\'efinition de ressource Devices qui vous permettent de d\'efinir +toutes les caract\'eristiques de votre p\'eriph\'erique de stockage. Heureusement, avec les +mat\'eriels modernes, les valeurs par d\'efaut sont g\'en\'eralement suffisantes, et tr\`es +peu de directives sont r\'eellement indispensables. + +Des exemples de directives de ressources device connues pour fonctionner pour +beaucoup de lecteurs de bandes communs peuvent \^etre trouv\'es dans le r\'epertoire : +\lt{}bacula-src\gt{}/examples/devices. La plupart seront \'enum\'er\'es ici. + +Pour une discussion g\'en\'erale concernant les fichiers de configuration de Bacula, +les ressources et les types de donn\'ees reconnus, veuillez consulter le +chapitre \ilink{Configuration}{_ChapterStart16} de ce manuel. Les d\'efinitions de +ressources Storage suivantes doivent \^etre d\'efinies : + +\begin{itemize} +\item + \ilink{Storage}{StorageResource} -- Pour d\'efinir le nom du Storage Daemon. +\item + \ilink{Director}{DirectorResource1} -- Pour d\'efinir le nom du Director et le mot + de passe permettant d'y acc\'eder. +\item + \ilink{Device}{DeviceResource} -- Pour d\'efinir les caract\'eristiques de votre + p\'eriph\'erique de stockage. +\item + \ilink{Messages}{_ChapterStart15} -- Pour d\'efinir o\`u les messages d'erreurs + et d'information doivent \^etre exp\'edi\'es. +\end{itemize} + +\section{Ressource Storage} +\label{StorageResource} +\index[general]{Ressource!Storage} +\index[general]{Ressource Sorage} +\addcontentsline{toc}{section}{Ressource Storage} + +En g\'en\'eral, les propri\'et\'es sp\'ecifi\'ees au niveau de la ressource Storage d\'efinissent +des propri\'et\'es globales du Storage Daemon. Chaque fichier de configuration de +Storage Daemon doit avoir sa propre d\'efinition de ressource Storage. + +\begin{description} + +\item [Name = \lt{}Storage-Daemon-Name\gt{}] + \index[sd]{Name} + \index[sd]{Directive!Name} + Sp\'ecifie le nom du Storage Daemon. Cette directive est requise. +\item [Working Directory = \lt{}R\'epertoire\gt{}] + \index[sd]{Working Directory} + \index[sd]{Directive!Working Directory} + Cette directive sp\'ecifie un r\'epertoire o\`u le Storage Daemon peut placer ses fichiers + d'\'etat. Ce r\'epertoire ne devrait \^etre utilis\'e que par Bacula, mais peut \^etre + partag\'e par d'autres daemons Bacula, pourvu que les noms donn\'es \`a chaque daemon + soient uniques. Cette directive est requise. + +\item [Pid Directory = \lt{}R\'epertoire\gt{}] + \index[sd]{Pid Directory} + \index[sd]{Directive!Pid Directory} + Cette directive sp\'ecifie un r\'epertoire o\`u le Storage Daemon peut d\'eposer son fichier +d'Id de processus. Ce fichier est utilis\'e pour stopper Bacula et pr\'evenir l'ex\'ecution +simultan\'ee de plusieurs copies de Bacula. Les substitutions shell standard sont +effectu\'ees \`a la lecture du fichier de configuration, de sorte que des valeurs +telles que {\bf \$HOME} seront correctement substitu\'ees. + +Typiquement, sur les syst\`emes Linux, vous utiliserez ici {\bf /var/run}. Si vous +n'installez pas Bacula dans les r\'epertoires syst\`eme, vous pouvez utiliser le +r\'epertoire de travail {\bf Working Directory} d\'efini plus haut. +Cette directive est requise. + +\item [Heartbeat Interval = \lt{}P\'eriode\gt{}] + \index[sd]{Heartbeat Interval} + \index[sd]{Directive!Heartbeat Interval} + \index[general]{Heartbeat Interval} + \index[general]{Broken pipe} + Cette directive d\'efinit la p\'eriode des pulsations \'emises par le Storage Daemon + vers le File Daemon lorqu'il (le SD) se trouve en situation d'attente du montage + d'une cartouche par l'op\'erateur. La valeur par d\'efaut est z\'ero, ce qui d\'esactive + les pulsations. Cette fonctionnalit\'e est particuli\`erement utile si vous avez un + routeur (tel que les 3Com) qui ne suit pas les standards Internet et expire une + connection valide apr\`es une courte dur\'ee, bien que {\it keepalive} soit activ\'e. + Ceci produit habituellement un message d'erreur du type {\it broken pipe}. + +\item [Maximum Concurrent Jobs = \lt{}nombre\gt{}] + \index[sd]{Maximum Concurrent Jobs} + \index[sd]{Directive!Maximum Concurrent Jobs} + O\`u \lt{}nombre\gt{} est nombre maximal de jobs qui peuvent \^etre ex\'ecut\'es + simultan\'ement. La valeur par d\'efaut est fix\'ee \`a 10, mais vous pouvez d\'efinir + une valeur plus grande. Chaque connexion depuis le Director (par exemple + une requ\^ete de statut, le lancement d'un job...) est consid\'er\'ee comme un job, + aussi, si vous voulez conserver la possibilit\'e d'utiliser la commande + {\bf status} dans la console alors qu'un job est en cours d'ex\'ecution, vous + devez utiliser une valeur strictement sup\'erieure \`a 1. Pour ex\'ecuter plusieurs + jobs simultan\'ement, vous devez param\'etrer plusieurs autres directives dans le + fichier de configuration du Director. Selon ce que vous voulez faire, il faudra + intervenir sur l'un ou l'autre param\`etre, mais vous devrez presque surement + r\'egler le param\`etre {\bf Maximum Concurrent Jobs} de la ressource Storage du + fichier de configuration du Director, et peut-\^etre aussi ceux des ressources + Job et Client. + +\item [SDAddresses = \lt{}Adresse IP\gt{}] + \index[sd]{SDAddresses} + \index[sd]{Directive!SDAddresses} + Pr\'ecise les ports et adresses sur lesquels le Storage Daemon est \`a + l'\'ecoute de connections du Director. En principe, les valeurs par d\'efaut sont + suffisantes, et vous n'avez pas besoin d'utiliser cette directive. La meilleure + explication du fonctionnement de cette directive est certainement un exemple : + +\footnotesize +\begin{verbatim} + SDAddresses = { ip = { + addr = 1.2.3.4; port = 1205; } + ipv4 = { + addr = 1.2.3.4; port = http; } + ipv6 = { + addr = 1.2.3.4; + port = 1205; + } + ip = { + addr = 1.2.3.4 + port = 1205 + } + ip = { + addr = 1.2.3.4 + } + ip = { + addr = 201:220:222::2 + } + ip = { + addr = bluedot.thun.net + } +} +\end{verbatim} +\normalsize + +o\`u "ip", "ip4", "ip6", "addr", et "port" sont des mots-clef. Notez que les adresses +peuvent \^etre sp\'ecifi\'ees sous forme de quadruplets point\'es, de nom symboliques +(uniquement dans la sp\'ecification "ip") ou en notation IPv6 \`a double points. Le port +peut quand \`a lui \^etre sp\'ecifi\'e par son num\'ero, ou par sa valeur mn\'emonique du +fichier /etc/services. Si un port n'est pas sp\'ecifi\'e, la valeur par d\'efaut est +utilis\'ee. Si une section ip est sp\'ecifi\'ee, la r\'esolution peut \^etre r\'ealis\'ee +par ipv4 ou ipv6. En revanche, si ip4 ou ip6 est sp\'ecifi\'ee, seule la r\'esolution +correspondante fonctionne. + +Vous pouvez, avec ces directives, remplacer les valeurs des directives SDPort et +SDAddress montr\'ees ci-dessous. + +\item [SDPort = \lt{}Num\'ero de port\gt{}] + \index[sd]{SDPort} + \index[sd]{Directive!SDPort} + Sp\'ecifie le num\'ero de port sur lequel le Storage Daemon \'ecoute les connexions + en provenance du Director. La valeur par d\'efaut est 9103. + +\item [SDAddress = \lt{}Adresse IP\gt{}] + \index[sd]{SDAddress} + \index[sd]{Directive!SDAddress} + Cette directive est optionnelle. Lorsqu'elle est sp\'ecifi\'ee, le Storage Daemon n'accepte + de connections (de Director(s) ou de File(s) Daemon(s)) que de l'adresse sp\'ecifi\'ee + {\bf Adresse-IP}, qui peut \^etre + soit un nom de domaine, soit une adresse IP au format quadruplet point\'e. + Si cette directive n'est pas sp\'ecifi\'ee, le Storage Daemon acceptera des connections de + de toute adresse valide. + +\end{description} + +Voici une d\'efinition typique d'une ressource Storage du Storage Daemon : + + +\footnotesize +\begin{verbatim} +# +# "Global" Storage daemon configuration specifications appear +# under the Storage resource. +# +Storage { + Name = "Storage daemon" + Address = localhost + WorkingDirectory = "~/bacula/working" + Pid Directory = "~/bacula/working" +} +\end{verbatim} +\normalsize + +\section{La ressource Director} +\label{DirectorResource1} +\index[general]{Ressource Director} +\index[general]{Resource!Director} +\addcontentsline{toc}{section}{La ressource Director} + +La ressource Director sp\'ecifie le nom du Director qui est autoris\'e +\`a utiliser les services du Storage Daemon. Il peut exister plusieurs +ressources Director. Le nom et le mot de passe du Director doivent +s'accorder avec leurs homologues dans le fichier de configuration +du Storage Daemon. + +\begin{description} + +\item [Name = \lt{}Nom-du-Director\gt{}] + \index[sd]{Name} + \index[sd]{Directive!Name} + Sp\'ecifie le nom du Director autoris\'e \`a se connecter au Storage Daemon. + Cette directive est requise. + +\item [Password = \lt{}Mot-de-passe-du-Director\gt{}] + \index[sd]{Password} + \index[sd]{Directive!Password} + Sp\'ecifie le mot de passe qui doit \^etre soumis par le Director susnomm\'e. + Cette directive est requise. + +\item [Monitor = \lt{}yes|no\gt{}] + \index[sd]{Monitor} + \index[sd]{Directive!Monitor} + Si cette directive est d\'esactiv\'ee ({\bf no}), ce qui est le cas par d\'efaut, + ce Director dispose d'un acc\`es illimit\'e \`a ce Storage Daemon. Dans le cas + contraire, ce Director est brid\'e de fa\c {c}on \`a pouvoir seulement r\'ecup\'erer le + statut courant de ce Storage Daemon. + + Si ce Director est utilis\'e par un superviseur, nous vous recommandons + fortement d'activer cette directive pour \'eviter de s\'erieux probl\`emes de + s\'ecurit\'e. + +\end{description} + +Voici un exemple d'une d\'efinition de ressource Director valide : + +\footnotesize +\begin{verbatim} +Director { + Name = MainDirector + Password = my_secret_password +} +\end{verbatim} +\normalsize + +\label{DeviceResource} +\section{La Ressource Device} +\index[general]{Resource!Device} +\index[general]{Ressource Device} +\addcontentsline{toc}{section}{Ressource Device} + +La ressource Device sp\'ecifie les d\'etails de chaque p\'eriph\'erique (en g\'en\'eral, +un lecteur de bandes) qui peut \^etre utilis\'e par le Storage Daemon. Un +Storage Daemon peut disposer de plusieurs ressources Device. En g\'en\'eral, +les propri\'et\'es sp\'ecifi\'ees dans la ressource Device sont sp\'ecifiques +au p\'eriph\'erique. + +\begin{description} + +\item [Name = {\it Nom-de-p\'eriph\'erique}] + \index[sd]{Name} + \index[sd]{Directive!Name} + Sp\'ecifie le nom que le Director devra utiliser pour d\'esigner ce p\'eriph\'erique. + Il s'agit d'un nom logique, c'est une cha\^ine qui peut comporter jusqu'\`a 127 + caract\`eres. C'est en g\'en\'eral une bonne id\'ee d'utiliser un nom qui corresponde + au nom "humain" du p\'eriph\'erique (NDT: la vo dit "the english name"). Le nom + physique du p\'eriph\'erique est sp\'ecifi\'e au niveau de la directive {\bf Archive Device} + d\'ecrite ci-dessous. Le nom que vous sp\'ecifiez ici est aussi utilis\'e dans le + fichier de configuration de votre Director au niveau de la + \ilink{directive Device}{StorageResource2} de sa ressource Storage. + +\item [Archive Device = {\it cha\^ine-nom}] + \index[sd]{Archive Device} + \index[sd]{Directive!Archive Device} + La {\bf cha\^ine-nom} (NDT : name-string dans la vo) sp\'ecifie le nom de fichier syst\`eme + du p\'eriph\'erique de stockage g\'er\'e par ce daemon. Il s'agit en g\'en\'eral d'un nom + de p\'eriph\'erique amovible, par exemple un lecteur de bande d\'esign\'e par "{\bf /dev/nst0}" + ou "{\bf /dev/rmt/0mbn}". Dans le cas d'un graveur de DVD, ce sera par exemple + {\bf /dev/hdc}. Ce peut \^etre aussi un un nom de r\'epertoire si vous sauvegardez + sur disque. Dans ce cas, vous devez soumettre le chemin absolu vers ce + r\'epertoire. Lorsque vous utilisez un lecteur de bandes, il est pr\'ef\'erable + d'utiliser la variante "non-rewind" du fichier de p\'eriph\'erique. De plus, sur les + syst\`emes tels que Sun, qui disposent de plusieurs m\'ethodes d'acc\`es aux cartouches, + prenez soin de sp\'ecifier l'usage de la convention I/O Berkeley avec les p\'eriph\'eriques. + le {\bf b} de la sp\'ecification {\bf /dev/rmt/0mbn} Solaris (Sun) est ce qui est + requis dans ce cas. Bacula ne supporte pas le comportement SysV des lecteurs de bandes. + + Comme mentionn\'e plus haut,Archive Device est, en principe, le nom d'un lecteur de bandes, + mais vous pouvez tout aussi bien sp\'ecifier le chemin absolu vers un r\'epertoire + existant. Dans ce cas, Bacula utilisera un fichier pour stocker les donn\'ees dans + le r\'epertoire sp\'ecifi\'e, le nom de fichier utilis\'e sera celui du volume tel que + sp\'ecifi\'e dans le catalogue. Si vous souhaitez \'ecrire dans plusieurs r\'epertoires + (dans le but de r\'epartir la charge sur plusieurs disques), vous devez d\'efinir deux ressources + Device, chacune comportant une Archive Device avec un r\'epertoire diff\'erent. + + Une troisi\`eme possibilit\'e consiste \`a sp\'ecifier le nom d'un FIFO. Un FIFO est un + fichier sp\'ecial qui connecte deux programmes via la m\'emoire du noyau. Si vous + sp\'ecifiez un FIFO en guise d'Archive Device, vous devez avoir un programme qui + lit ce que Bacula \'ecrit dans le FIFO. Lorsque le Storage Daemon d\'emarre le job, + il attend que le programme lecteur commence \`a lire pendant un d\'elai maximal de + de {\bf MaximumOpenWait} secondes, au del\`a duquel le job est termin\'e. Par cons\'equent, + il est pr\'ef\'erable de lancer le programme lecteur au d\'ebut du job, par exemple + gr\^ace \`a la directive {\bf RunBeforeJob}. Pour ce type de p\'eriph\'erique, vous ne devez + jamais sp\'ecifier {\bf AlwaysOpen}, puisque vous voulez que le Storage Daemon + ne l'ouvre que lorsqu'un job d\'emarre, aussi veuillez attribuer explicitement + la valeur {\bf No} \`a cette directive. Puisqu'un FIFO est un p\'eriph\'erique \`a sens + unique, Bacula ne tente pas d'en lire le label, il se contente d'y \'ecrire. Pour + cr\'eer un volume FIFO dans le catalogue, utilisez la commande {\bf add} plut\^ot + que la commande {\bf label} afin d'\'eviter de tenter d'\'ecrire un label. + + Lors d'une op\'eration de restauration, si l'Archive Device est un FIFO, Bacula + tente de lire le FIFO, aussi vous devez avoir un programme externe qui \'ecrit dans + le FIFO. Bacula attend que ce programme commence \`a \'ecrire pendant un d\'elai + maximal de {\bf MaximumOpenWait} secondes apr\`es quoi il termine le job. Comme + mentionn\'e ci-dessus, vous pouvez utiliser la directive {\bf RunBeforeJob} pour + lancer ce programme auteur d\`es le d\'ebut du job. + + La directive Archive Device est requise. + +\item [Device Type = {\it Sp\'ecification-de-type}] + \index[sd]{Device Type} + \index[sd]{Directive!Device Type} + La sp\'ecification Device Type de d\'eclarer explicitement \`a Bacula quel type + de p\'eriph\'erique vous d\'efinissez. La valeur de {\it Sp\'ecification-de-type} peut + \^etre l'une des suivantes : + \begin{description} + \item [File] + Indique \`a Bacula que le p\'eriph\'erique est un fichier. Ce peut \^etre + un fichier d\'efini sur un m\'edium fixe ou au contraire amovible (par exemple, un + p\'eriph\'erique USB). Tous les fichiers doivent \^etre des p\'eriph\'eriques en acc\`es + s\'electif (NDT : traduction Google sans doute \`a revoir de "random access") + \item[tape] + Indique \`a Bacula que le p\'eriph\'erique est un lecteur de bandes, donc \`a + acc\`es s\'equentiel. Ces p\'eriph\'eriques sont control\'e par les appels + ioctl(). + \item[Fifo] + Indique \`a Bacula que le p\'eriph\'erique est un p\'eriph\'erique \`a acc\`es + s\'equentiel "first-in-first-out" (premier entr\'e, premier sorti) en + lecture seule ou en \'ecriture seule. + \item[DVD] + Indique \`a Bacula que le p\'eriph\'erique est un DVD. Les DVDs sont \`a acc\`es + s\'equentiel en \'ecriture et \`a acc\`es s\'electif (NDT : traduction Google sans + doute \`a revoir de "random access") en lecture. + \end{description} + + La directive Device Type n'est pas requise, et si elle n'est pas sp\'ecifi\'ee, + Bacula tentera de deviner cette information selon la sp\'ecification Archive + Device fournie. Il existe plusieurs avantages \`a sp\'ecifier explicitement + le type de p\'eriph\'erique. D'abord, sur certains syst\`emes, les p\'eriph\'eriques + bloc et caract\`ere ont le m\^eme type, ce qui signifie que sur ces syst\`emes, + Bacula est probablement incapable de deviner qu'un p\'eriph\'erique est un DVD. + Ensuite, si vous sp\'ecifiez explicitement le type de p\'eriph\'erique, le point de + montage n'a pas besoin d'\^etre d\'efini jusqu'\`a ce que le p\'eriph\'erique soit ouvert. + C'est le cas de la plupart des p\'eriph\'eriques amovibles tels que les USB mont\'es + par le daemon HAL. Au contraire, si le type de p\'eriph\'erique n'est pas + sp\'ecifi\'e explicitement, le point de montage doit exister d\`es le + d\'emarrage du Storage Daemon. + + Cette directive est apparue avec la version 1.38.6 de Bacula. + +\item [Media Type = {\it name-string}] + \index[sd]{Media Type} + \index[sd]{Directive!Media Type} + La cha\^ine {\bf name-string} sp\'ecifi\'ee baptise le type de m\'edia support\'e par + ce p\'eriph\'erique, par exemple, "DLT7000". Les noms de type de m\'edia sont + arbitraires, vous pouvez utiliser le nom de votre choix, mais ils doivent + \^etre connus du catalogue pour qu'il puisse garder trace de quel daemon + peut lire quel type de m\'edia. En g\'en\'eral, chaque type de stockage devrait + avoir un type de m\'edia unique associ\'e. Le m\^eme nom {\bf name-string} doit + appara\^itre dans la d\'efinition de ressource Storage appropri\'ee du fichier + de configuration du Director. + + M\^eme si les noms que vous assignez sont arbitraires, vous devriez les choisir + avec circonspection, car le Media Type est utilis\'e pour d\'eterminer le + p\'eriph\'erique de stockage \`a s\'electionner lors d'une restauration. Ainsi, vous + devriez certainement utiliser le m\^eme Media Type pour tous les lecteurs + dont les cartouches sont interchangeables. Ce n'est g\'en\'eralement pas un + probl\`eme si vous n'avez qu'un Storage Daemon, mais c'en est un avec plusieurs + Storage Daemon, surtout s'ils utilisent des m\'edia incompatibles. + + Si, par exemple, vous sp\'ecifiez le Media Type "DDS-4", Bacula pourra lors de + restaurations s\'electionner tout Storage Daemon qui supporte les "DDS-4". + Si vous avez une librairie, vous voudrez peut-\^etre baptiser son Media Type + d'un nom qui lui soit unique, \`a moins que vous souhaitiez pouvoir utiliser + ses volumes dans d'autres lecteurs. Vous devriez aussi vous assurer d'avoir + des noms de Media Type uniques si les media ne sont pas compatibles d'un + lecteur \`a l'autre. Cette sp\'ecification est requise pour tous les + p\'eriph\'eriques. + + Enfin, si vous utilisez le stockage sur disque, sachez que chaque ressource + Device a g\'en\'eralement un point de montage (ou r\'epertoire) diff\'erent. Afin + que Bacula puisse s\'electionner correctement la ressource Device \`a utiliser, + chacun doit avoir un Media Type distinct. + +\label{Autochanger} +\item [Autochanger = {\it Yes|No}] + \index[sd]{Autochanger} + \index[sd]{Directive!Autochanger} + Si cette directive est \`a {\bf yes}, alors Bacula consid\`ere que le p\'eriph\'erique + concern\'e est dans une librairie, et il vous faut sp\'ecifier une ressource + {\bf Autochanger} qui pointe vers les ressources {\bf Device}. Vous devez + aussi renseigner la directive {\bf Changer Device}. Si la directive est \`a {\bf No} + (valeur par d\'efaut), les volumes doivent \^etre chang\'es manuellement. Vous devriez + aussi avoir une directive identique \`a la \ilink{Storage resource}{Autochanger1} dans + le fichier de configuration du Director, de sorte que Bacula vous demande le slot + lors de l'\'etiquetage des cartouches. + +\item [Changer Device = {\it cha\^ine-nom}] + \index[sd]{Changer Device} + \index[sd]{Directive!Changer Device} + La {\bf cha\^ine-nom} sp\'ecifi\'ee doit \^etre le nom de p\'eriph\'erique {\bf SCSI g\'en\'erique} + associ\'e \`a l'{\bf Archive Device} sp\'ecifi\'ee dans la ressource Device. Ce nom de + p\'eriph\'erique SCSI g\'en\'erique devrait \^etre sp\'ecifi\'e si vous avez une librairie + ou si vous n'avez qu'un lecteur standard mais souhaitez utiliser la {\bf commande + Alert} (voir ci-dessous). Par exemple, sur les syst\`emes Linux, vous sp\'ecifierez + certainement {\bf /dev/nst0} pour le nom d'Archive Device, et {\bf /den/sg0} pour + le nom de Changer Device. Selon votre configuration, le nombre de librairies dont + vous disposez et leurs types, le nom que vous serez amen\'e \`a sp\'ecifier ici peut varier. + Cette directive est optionnelle. Consultez le chapitre + \ilink{Utiliser une librairie}{_ChapterStart18} de ce manuel pour plus de d\'etails + concernant les directives relatives aux librairies. + +\item [Changer Command = {\it cha\^ine nom}] + \index[sd]{Changer Command} + \index[sd]{Directive!Changer Command} + La {\bf cha\^ine-nom} d\'esigne un programme externe qui aura pour t\^ache le + changement des volumes \`a la demande de Bacula. En principe, cette directive + n'est sp\'ecifi\'ee qu'au niveau de la ressource {\bf AutoChanger}, qui est alors + utilis\'ee pour tous les p\'eriph\'eriques. Cependant, vous pouvez parfaitement + utiliser une commande {\bf Changer Command} diff\'erente pour chaque ressource Device. + La plupart du temps, vous sp\'ecifierez le script {\bf mtx-changer} fourni avec + Bacula de la fa\c {c}on suivante : + +\footnotesize +\begin{verbatim} +Changer Command = "/path/mtx-changer %c %o %S %a %d" +\end{verbatim} +\normalsize + + Et vous installerez le programme {\bf mtx} sur votre syst\`eme (paquetage tiers). + Un exemple de cette commande figure dans le fichier de configuration par d\'efaut + du Storage Daemon, bacula-sd.conf. Pour plus de d\'etails concernant les + substitutions de caract\`eres qui peuvent \^etre utilis\'ees pour configurer + votre librairie, veuillez consulter le chapitre sur + l'\ilink{utilisation des Librairies}{_ChapterStart18}. Les utilisateurs + de FreeBSD voudront probablement jeter un oeil aux quelques scripts + fournis dans le r\'epertoire {\bf examples/autochangers}. + +\item [Alert Command = {\it name-string}] + \index[sd]{Alert Command} + La {\bf cha\^ine-nom} d\'esigne un programme externe \`a appeler au terme + de chaque job apr\`es que le p\'eriph\'erique ait \'et\'e lib\'er\'e. Le but de cette + commande est de r\'ecup\'erer d'\'eventuels messages d'alerte du lecteur pour + vous pr\'evenir si quelque chose ne fonctionne pas correctement (ces messages + existent au moins sur la plupart des lecteurs modernes). Les m\^emes + substitutions que celles d\'ecrites au niveau de la {\bf Changer command} + peuvent \^etre utilis\'ees ici. Pour plus d'informations, veuillez consulter + le chapitre sur les \ilink{Librairies}{_ChapterStart18} de ce manuel. + + Notez que vous pouvez trouver un usage \`a cette commande sans n\'ecessairement + poss\'eder une librairie. L'exemple ci-dessous utilise le programme {\bf tapeinfo} + qui vient avec le paquet {\bf mtx} mais peut \^etre utilis\'e avec n'importe quel + lecteur. Vous devrez tout de m\^eme sp\'ecifier une directive {\bf Changer Device} + dans votre ressource Device (voir ci-dessus) afin que le p\'eriph\'erique SCSI + g\'en\'erique puisse \^etre \'edit\'e dans la commande (avec \%c). + + Voici un exemple qui affiche les alertes en provenance du lecteur dans les + rapports de jobs : + +\footnotesize +\begin{verbatim} +Alert Command = "sh -c 'tapeinfo -f %c | grep TapeAlert'" + +\end{verbatim} +\normalsize + +Et un exemple de ce qui peut en sortir lorqu'il y a un probl\`eme : + +\footnotesize +\begin{verbatim} +bacula-sd Alert: TapeAlert[32]: Interface: Problem with SCSI interface + between tape drive and initiator. + +\end{verbatim} +\normalsize + +\item [Drive Index = {\it number}] + \index[sd]{Drive Index} + \index[sd]{Directive!Drive Index} + Le num\'ero de lecteur, ou {\bf Drive Index}, que vous sp\'ecifiez ici est + pass\'e au script {\bf mtx-changer} et donc au programe {\bf mtx}. + Par d\'efaut, le Drive Index vaut z\'ero, aussi, si vous n'avez qu'un + lecteur dans votre librairie, tout fonctionnera correctement. + Si en revanche vous avez plusieurs lecteurs, vous devez sp\'ecifier + plusieurs ressources Device (une par lecteur). + Il n'est pas n\'ecessaire de sp\'ecifier la valeur z\'ero pour la directive + Drive Index dans la premi\`ere de ces ressources (valeur par d\'efaut). Par + contre, la seconde devrait contenir une directive Drive Index \'egale \`a 1, + la troisi\`eme une directive Drive Index \'egale \`a 2, et ainsi de suite. + A partir de la version 1.38.0, en utilisant la ressource {\bf Autochanger}, + Bacula s'assure qu'un seul lecteur \`a la fois utilise le script d'autochargement + (script mtx-changer), aussi vous n'avez plus besoin de scripts de verrouillage + comme ce fut le cas dans le pass\'e -- Le script mtx-change fourni avec Bacula + fonctionne avec un nombre quelconque de lecteurs. + +\item [Autoselect = {\it Yes|No}] + \index[sd]{Autoselect} + \index[sd]{Directive!Autoselect} + Si cette directive vaut {\bf yes} (valeur par d\'efaut), et si le p\'eriph\'erique + appartient \`a une librairie, alors lorsque la librairie est r\'ef\'erenc\'ee par + le Director, ce p\'eriph\'erique peut \^etre automatiquement s\'electionn\'e. + Si cette directive vaut {\bf no}, alors le p\'eriph\'erique peut seulement + \^etre d\'esign\'e par son nom de p\'eriph\'erique (Device Name) dans le + Director. Ceci permet de r\'eserver un lecteur pour une t\^ache particuli\`ere, + comme une sauvegarde hautement prioritaire, ou des op\'erations de restaurations. + +\item [Maximum Changer Wait = {\it time}] + \index[sd]{Maximum Changer Wait} + \index[sd]{Directive!Maximum Changer Wait} + Cette directive sp\'ecifie le d\'elai maximum, en secondes, pendant lequel Bacula + peut attendre d'une librairie qu'elle change de volume. Au del\`a de ce d\'elai, + Bacula invalide le num\'ero de slot r\'ef\'erenc\'e dans le catalogue et essaye \`a + nouveau. Si aucun autre volume n'est disponible dans la librairie, Bacula + r\'eclame l'intervention d'un op\'erateur. La valeur par d\'efaut est 5 minutes. + +\item [Maximum Rewind Wait = {\it time}] + \index[sd]{Maximum Rewind Wait} + \index[sd]{Directive!Maximum Rewind Wait} + Cette directive sp\'ecifie le d\'elai maximum, en secondes, pendant lequel Bacula + peut attendre d'un lecteur qu'il rembobine une cartouche. Au del\`a de ce d\'elai, + le job est effac\'e. La valeur par d\'efaut est 5 minutes. + +\item [Maximum Open Wait = {\it time}] + \index[sd]{Maximum Open Wait} + \index[sd]{Directive!Maximum Open Wait} + Cette directive sp\'ecifie le d\'elai maximum, en secondes, pendant lequel Bacula + peut attendre apr\`es une commande Open.Au del\`a de ce d\'elai, + le job est effac\'e. La valeur par d\'efaut est 5 minutes. + +\item [Always Open = {\it Yes|No}] + \index[sd]{Always Open} + \index[sd]{Directive!Always Open} + Si la valeur sp\'ecifi\'ee ici est {\bf Yes} (valeur par d\'efaut), Bacula garde le + p\'eriph\'erique ouvert, \`a moins qu'il ne soit explicitement d\'emont\'e ({\bf unmounted}) + depuis la console Bacula. Ceci permet \`a Bacula de s'assurer que le lecteur est + toujours disponible. Si vous r\'eglez {\bf AlwaysOpen} \`a {\bf no} {\bf Bacula}, + Bacula ouvre le lecteur seulement lorsque n\'ecessaire, et le lib\`ere \`a la fin du + job, si aucun autre job ne l'utilise. Lors de l'utilisation suivante, Bacula + doit rembobiner la cartouche et se repositionner au bon endroit. Pour \'eviter + ces rembnobinages inutiles et les interventions de l'op\'erateur, il est + hautement recommand\'e de garder la valeur {\bf Always Open = yes}. Ceci assure + aussi que le lecteur est disponible lorsque Bacula en a besoin. + + Si vous avez sp\'ecifi\'e {\bf Always Open = yes} (comme recommand\'e) et si vous + voulez utiliser le lecteur pour autre chose, lib\'erez-le simplement avec la + commande {\bf unmount} dans la console Bacula. N'oubliez-pas ensuite de + remonter le lecteur avec la commande {\bf mount} afin que Bacula soit pr\`et + \`a prendre en charge le prochain job planifi\'e. + + Pour le stockage sur disque (File Storage), cette directive est ignor\'ee. Dans le + cas d'un stockage FIFO, vous devez mettre cette directive \`a {\bf No}. + + Notez bien que si vous mettez cette directive \`a {\bf No}, Bacula lib\`ere le + lecteur entre chaque job, obligeant le lecteur \`a rembobiner la cartouche, et + \`a replacer la bande \`a la fin de la zone de donn\'ees, ce qui peut prendre + beaucoup de temps. + +\item [Volume Poll Interval = {\it p\'eriode}] + \index[sd]{Volume Poll Interval} + \index[sd]{Directive!Volume Poll Interval} + Si la p\'eriode sp\'ecifi\'ee pour cette directive est non nulle alors, apr\`es avoir + demand\'e \`a l'op\'erateur de monter un nouveau volume, Bacula retentera + p\'eriodiquement de lire le lecteur selon la p\'eriode sp\'ecifi\'ee au cas o\`u un + nouveau volume aurait \'et\'e mont\'e. Si la valeur sp\'ecifi\'ee est z\'ero, ces + tentatives de lecture n'ont pas lieu. Cette directive est utile lorsque + vous souhaitez \'eviter l'intervention d'un op\'erateur \`a la console. Au lieu de + quoi l'op\'erateur se contente de sortir la cartouche pr\'ec\'edente et de monter la + nouvelle qui sera reconnue \`a la prochaine tentative. Soyez conscient que si vous + sp\'ecifiez une p\'eriode trop courte, vous risquez de solliciter excessivement + votre lecteur si la cartouche pr\'ec\'edente demeure dans le lecteur, puisque Bacula + la lira \`a chaque tentative. Vous pouvez \'eviter ceci en \'ejectant la cartouche avec + les directives {\bf Offline On Unmount} et {\bf Close on Poll}. + Cependant, si vous utilisez un noyau Linux 2.6 ou un autre syst\`eme d'exploitation tel + FreeBSD ou Solaris, les commandes Offline ou Unmount laisseront le lecteur sans cartouche, + et Bacula, incapable de d'ouvrir correctement le lecteur, pourrait \'echouer ses jobs. + Pour plus d'informations sur ce probl\`eme, veuillez consulter la section + \ilink{description of Offline On Unmount}{NoTapeInDrive} du chapitre relatif + aux tests des lecteurs de bandes. + +\item [Close on Poll= {\it Yes|No}] + \index[sd]{Close on Poll} + \index[sd]{Directive!Close on Poll} + Si cette directive est \`a {\bf Yes}, Bacula ferme le p\'eriph\'erique et le r\'eouvre + \`a chaque tentative (ce qui est \'equivalent \`a unmount, sauf qu'il n'est pas + n\'ecessaire d'utiliser mount ensuite). En principe, cette directive n'est + pas tr\`es utile \`a moins que vous ayez activ\'e la directive {\bf Offline on Unmount}, + auquel cas le lecteur sera consid\'er\'e hors-ligne (NDT : offline) pr\'evenant ainsi + de nombreux mouvements inutiles de la bande lors de chaque tentative de lecture. + Une fois que l'op\'erateur aura charg\'e une nouvelle cartouche, Bacula + sera en mesure de s'en rendre compte \`a la prochaine tentative et poursuivra + automatiquement la sauvegarde. Voyez ci-dessus pour plus de d\'etails. + +\item [Maximum Open Wait = {\it time}] + \index[sd]{Maximum Open Wait} + \index[sd]{Directive!Maximum Open Wait} + Cette directive sp\'ecifie le d\'elai maximum, en secondes que Bacula + accorde \`a un p\'eriph\'erique occup\'e. La valeur par d\'efaut est 5 minutes. + Si le p\'eriph\'erique ne peut \^etre obtenu, le job en cours est termin\'e en erreur. + Bacula tentera \`a nouveau d'ouvrir le lecteur lorsqu'un nouveau job le + r\'eclamera. + +\item [Removable media = {\it Yes|No}] + \index[sd]{Removable media} + \index[sd]{Directive!Removable media} + R\'eglez cette directive \`a {\bf Yes} si le p\'eriph\'erique concern\'e supporte des + m\'edia amovibles (par exemple des cartouches ou des CDROMs). Dans le cas de + m\'edia inamovibles (par exemple, une zone de sauvegardes interm\'ediaires sur un + disque dur), mettez {\bf Removable media = No} + +\item [Random access = {\it Yes|No}] + \index[sd]{Random access} + \index[sd]{Directive!Random access} + Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique de stockage est consid\'er\'e + comme \'etant un m\'edium \`a acc\`es al\'eatoire (NDT : random access medium) qui + supporte les commodit\'es {\bf lseek} (ou {\bf lseek64} si l'option Largefile + a \'et\'e activ\'ee lors de la compilation). + +\item [Minimum block size = {\it size-in-bytes}] + \index[sd]{Minimum block size} + \index[sd]{Directive!Minimum block size} + Sur la plupart des lecteurs modernes, vous n'aurez pas besoin de cette + directive, dont le but est d'utiliser des blocs de taille fixe. Cette + directive ne s'applique qu'aux p\'eriph\'eriques \`a acc\`es s\'equentiel (NDT : + non-random access devices) comme, par exemple, les lecteurs de bandes. + Les blocs \'ecrits par le Storage Daemon sur un p\'eriph\'erique \`a acc\`es + s\'equentiel ne seront jamais de taille inf\'erieure \`a la taille sp\'ecifi\'ee + {\bf size-in-bytes}. Le Storage Daemon tente de remplir au mieux les blocs + avec les donn\'ees re\c {c}ues, mais il compl\`ete si n\'ecessaire pour atteindre + la taille minimum requise {\bf Minimum block size} . + + Pour contraindre la taille des blocs \`a \^etre fixe, comme c'est le cas de + certains p\'eriph\'eriques \`a acc\`es s\'equentiel, stipulez des tailles de blocs + minimum {\bf Minimum block size} et maximum {\bf Maximum block size} + identiques. Le param\'etrage par d\'efaut est 0 pour les deux directives + et la taille de bloc par d\'efaut est de 64 512 octets. + + Par exemple, si vous souhaitez fixer la taille des blocs \`a 100K octets, sp\'ecifiez : + +\footnotesize +\begin{verbatim} + + Minimum block size = 100K + Maximum block size = 100K + +\end{verbatim} +\normalsize + Notez que si vous sp\'ecifiez une taille de blocs fixe comme ci-dessus, le + lecteur doit \^etre r\'egl\'e soit en mode "taille de blocs variable", soit en + mode "taille de blocs fixe" avec imp\'erativement la m\^eme taille de blocs + fixe que celle sp\'ecifi\'ee dans Bacula (ce param\`etre se r\`egle g\'en\'eralement + au niveau du lecteur avec {\bf mt}), faute de quoi vous aurez des erreurs \`a + la relecture de vos cartouches. + + Si vous voulez que votre taille de blocs soit variable mais comprise entre + 64 Ko et 200 Ko, sp\'ecifiez : + +\footnotesize +\begin{verbatim} + + Minimum block size = 64K + Maximum blocksize = 200K + +\end{verbatim} +\normalsize + +\item [Maximum block size = {\it size-in-bytes}] + \index[sd]{Maximum block size} + \index[sd]{Directive!Maximum block size} + Sur la plupart des lecteurs modernes, vous n'aurez pas besoin de cette + directive. Dans le cas contraire, ce sera probablement pour utiliser + des blocs de taille fixe (voir la directive Minimum block size ci dessus). + Le Storage Daemon tente d'\'ecrire des blocs de la taille sp\'ecifi\'ee + {\bf size-in-bytes} sur le p\'eriph\'erique. Par cons\'equent cette + directive fixe \`a la fois la taille maximale et la taille par d\'efaut + des blocs. La taille \'ecrite n'exc\`ede jamais la taille sp\'ecifi\'ee ici. + Lorsque l'ajout de donn\'ees provoquerait un d\'epassement, le bloc est + \'ecrit sur le p\'eriph\'erique, et un nouveau bloc est entam\'e. + avec les donn\'ees re\c {c}ues, mais il compl\`ete si n\'ecessaire pour atteindre + + Si aucune valeur n'est sp\'ecifi\'ee (ou si la valeur sp\'ecifi\'ee est 0), le + Storage Daemon utilise la valeur par d\'efaut de 64 512 octets. + +\item [Hardware End of Medium = {\it Yes|No}] + \index[sd]{Hardware End of Medium} + \index[sd]{Directive!Hardware End of Medium} + Si la valeur attribu\'ee \`a cette directive est {\bf No}, le p\'eriph\'erique de + stockage n'a pas besoin de supporter les requ\^etes ioctl "fin de m\'edium", + le Storage Daemon utilisant la fonction d'avance jusqu'au prochain espace + pour trouver la fin du m\'edium. Si la valeur est {\bf Yes}, le p\'eriph\'erique + doit supporter l'appel {\tt ioctl} {\tt MTEOM} qui positionne la cartouche + \`a la fin des donn\'ees enregistr\'ees. De plus, votre driver SCSI doit garder trace + du nombre de fichiers enregistr\'es sur la cartouche, et le retourner correctement + \`a l'appel {\bf MTIOCGET} ioctl. Notez que certains pilotes SCSI savent se + positionner correctement \`a la fin de la zone de donn\'ees enregistr\'ees sur la cartouche, + mais ne gardent pas trace du nombre de fichiers. Sur les machines Linux, le + driver SCSI a une option {\bf fast-eod} qui, si elle est utilis\'ee + provoque la perte du nombre de fichiers. assurez-vous toujours que cette + option est bien d\'esactiv\'ee (\`a l'aide du programme {\bf mt}). + + Le r\'eglage par d\'efaut de cette directive est {\bf Yes}. Cette option est utilis\'ee + lors de l'\'ecriture \`a la suite d'une cartouche, pour s'assurer que les donn\'ees + pr\'ec\'edemment \'ecrites ne seront pas corrompues. Nous vous recommandons, si vous + avez un lecteur non-standard ou inhabituel, de le tester avec le programme + {\bf btape} pour v\'erifier s'il supporte ou non cette fonction. Tous les lecteurs + modernes (au del\`a de 1998) la supportent. + +\item [Fast Forward Space File = {\it Yes|No}] + \index[sd]{Fast Forward Space File} + \index[sd]{Directive!Fast Forward Space File} + Si la valeur attribu\'ee \`a cette directive est {\bf No}, le p\'eriph\'erique de + stockage n'a pas besoin de supporter les requ\^etes ioctl {\bf MTIOCGET} + "nombre de fichiers" lors du d\'eplacement sur la bande jusqu'au prochain espace. Si au contraire + vous sp\'ecifiez {\bf yes}, le lecteur doit supporter l'appel {\tt ioctl} {\tt MTFSF}, + que presque tous les pilotes supportent, mais de plus votre pilote SCSI doit + garder trace et retourner correctement le nombre de fichiers \`a l'appel + ioctl {\bf MTIOCGET} . Notez que certains pilotes SCSI ex\'ecutent correctement + les d\'eplacements sur bande "jusqu'au prochain espace" sans toutefois garder trace + du nombre de fichiers enregistr\'es, et m\^eme plus grave pour certains : sans + signaler la fin du support. + + La valeur par d\'efaut de cette directive est {\bf Yes}. + +\item [Use MTIOCGET = {\it Yes|No}] + \index[sd]{Use MTIOCGET} + \index[sd]{Directive!Use MTIOCGET} + Si la valeur attribu\'ee \`a cette directive est {\bf No}, le syst\`eme d'exploitation + n'a pas besoin de garder trace du nombre de fichiers sur la cartouche, ni de + le retourner \`a l'appel ioctl {\bf MTIOCGET}. La valeur par d\'efaut est {\bf Yes}. + Si vous devez mettre No ici, Bacula prendra en charge la d\'etermination des + positions de fichiers, mais cela implique des mouvements tr\`es inefficaces de la + bande. Heureusement, cette d\'eficience du syst\`eme d'exploitation semble n'\^etre + l'apanage que de quelques *BSD. Solaris, Linux et FreeBSD sont connus pour + fonctionner correctement. + +\item [BSF at EOM = {\it Yes|No}] + \index[sd]{BSF at EOM} + \index[sd]{Directive!BSF at EOM} + Si cette directive est \`a {\bf No} (valeur par d\'efaut), Bacula n'entreprend + aucune action particuli\`ere lorsque la fin du m\'edium est atteinte car + la cartouche est positionn\'ee apr\`es la derni\`ere marque de fin de fichier EOF, + et Bacula peut \'ecrire \`a la suite. Cependant, sur certains syst\`emes tels que + FreeBSD, lorsque Bacula lit la marque de fin de cartouche, la cartouche est + positionn\'ee apr\`es la seconde marque de fin de fichier EOF (deux marques EOF + successives indiquent la fin du support). Si Bacula \'ecrit au del\`a de cette + marque, toutes les donn\'ees ajout\'ees seront perdues. La solutions pour ces syst\`emes + consiste \`a sp\'ecifier {\bf BSF at EOM}, ainsi Bacula recule en \'ecrasant la + seconde marque de fin de fichier. Pour savoir si vous avez besoin de cette + directive, utilisez la commande {\bf test} du programme {\bf btape}. + +(NDT : Paragraphe \`a revoir VO ci dessous) + If {\bf No}, the default, no special action is taken by Bacula with the End + of Medium (end of tape) is reached because the tape will be positioned after + the last EOF tape mark, and Bacula can append to the tape as desired. + However, on some systems, such as FreeBSD, when Bacula reads the End of + Medium (end of tape), the tape will be positioned after the second EOF tape + mark (two successive EOF marks indicated End of Medium). If Bacula appends + from that point, all the appended data will be lost. The solution for such + systems is to specify {\bf BSF at EOM} which causes Bacula to backspace over + the second EOF mark. Determination of whether or not you need this directive + is done using the {\bf test} command in the {\bf btape} program. + +\item [TWO EOF = {\it Yes|No}] + \index[sd]{TWO EOF} + \index[sd]{Directive!TWO EOF} + Si cette directive est \`a {\bf Yes}, Bacula \'ecrit deux marques de fin de fichier EOF + lorsqu'il a fini d'utiliser une cartouche -- c'est \`a dire apr\`es le dernier + job, ou \`a la fin de la cartouche. Dans le cas contraire (la valeur par d\'efaut), + Bacula n'\'ecrit qu'une marque de fin de fichier pour terminer une cartouche. + +\item [Backward Space Record = {\it Yes|No}] + \index[sd]{Backward Space Record} + \index[sd]{Directive!Backward Space Record} + Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique supporte {\tt MTBSR ioctl} + pour reculer dans les enregistrements. Sinon, cet appel n'est pas utilis\'e + et la bande doit \^etre rembobin\'ee puis avanc\'ee de fichier en fichier jusqu'\`a + la position d\'esir\'ee. La valeur par d\'efaut est {\bf Yes} pour un p\'eriph\'erique + \`a acc\`es s\'equentiel. Cette fonction, si activ\'ee, est utilis\'ee \`a la fin des + volumes apr\`es \'ecriture d'une marque fin de fichier et de toute \'etiquette + ANSI/IBM pour d\'eterminer si oui ou non le dernier bloc a \'et\'e \'ecrit + correctement. Si vous d\'esactivez cette fonction, le test ne sera pas fait. + Ce n'est pas un probl\`eme car le processus de relecture est une + pr\'ecaution plut\^ot qu'une n\'ecessit\'e. + +\item [Backward Space File = {\it Yes|No}] + \index[sd]{Backward Space File} + \index[sd]{Directive!Backward Space File} + Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique supporte les appels + {\bf MTBSF} et {\bf ioctl MTBSF} pour reculer en-de\c{c}a d'un marque de fin de fichier + et se replacer au d\'ebut du fichier. Si cette directive est \`a {\bf No}, ces appels + ne sont pas utilis\'es et le lecteur doit rembobiner la cartouche, puis avancer + de fichier en fichier jusqu'\`a la position d\'esir\'ee. La valeur par d\'efaut est + {\bf Yes} pour les p\'eriph\'eriques \`a acc\`es s\'equentiel. + +\item [Forward Space Record = {\it Yes|No}] + \index[sd]{Forward Space Record} + \index[sd]{Directive!Forward Space Record} + Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique doit supporter les appels + {\bf MTFSR ioctl} pour avancer \`a travers les + enregistrements. Si la valeur est {\bf No}, les donn\'ees doivent \^etre lues dans l'ordre + pour positionner la cartouche. La valeur par d\'efaut est + {\bf Yes} pour les p\'eriph\'eriques \`a acc\`es s\'equentiel. + +\item [Forward Space File = {\it Yes|No}] + \index[sd]{Forward Space File} + \index[sd]{Directive!Forward Space File} + Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique doit supporter les appels + {\tt MTFSF ioctl} pour d\'eplacer la bande en se rep\'erant aux marques de fichiers. + Si la valeur est {\bf No}, les donn\'ees doivent \^etre lues pour positionner la + bande. La valeur par d\'efaut est + {\bf Yes} pour les p\'eriph\'eriques \`a acc\`es s\'equentiel. + +\item [Offline On Unmount = {\it Yes|No}] + \index[sd]{Offline On Unmount} + \index[sd]{Directive!Offline On Unmount} + Si cette directive est \`a {\bf Yes}, le p\'eriph\'erique doit supporter les appels + {\tt MTOFFL ioctl} pour rembobiner et placer le volume \`a l'\'etat {\it offline}. + Dans ce cas, Bacula lance requ\^ete {\it eject} avant de fermer le lecteur lors + de la commande {\bf unmount}. Si la valeur est {\bf No} (valeur par d\'efaut), + Bacula ne tente pas de mettre la cartouche \`a l'\'etat {\it offline} avant de + la d\'emonter. Apr\`es que la cartouche ait \'et\'e mise hors ligne, elle est \'eject\'ee + requ\'erant ainsi {\bf l'intervention d'un op\'erateur} pour poursuivre. Certains + syst\`emes exigent que la commande de chargement {\bf mt -f /dev/xxx load} + soit lanc\'ee avant de pouvoir reconna\^itre la cartouche. Si vous utilisez une + librairie, sachez que certaines requi\`erent de passer le lecteur \`a l'\'etat + {\it offline} pour pouvoir changer de cartouche. Cependant, la plupart n'en + on pas besoin et pourraient \^etre d\'erout\'es si cette directive est \`a {\bf Yes}. + + Si vous utilisez un noyau Linux 2.6, ou un syst\`eme tel que FreeBSD ou Solaris, + la directive Offline On Unmount abandonnera votre lecteur sans cartouche, et Bacula + incapable de l'utiliser. Pour plus d'informations sur ce probl\`eme, + consultez la section \ilink{description de Offline On Unmount}{NoTapeInDrive} dans le + chapitre sur les tests de lecteurs. + +\item [Maximum Volume Size = {\it size}] + \index[sd]{Maximum Volume Size} + \index[sd]{Directive!Maximum Volume Size} + Avec cette directive, vous pouvez imposer une limite au poids de donn\'ees + \`a \'ecrire sur chaque volume. La valeur {\bf size} repr\'esente le nombre d'octets + autoris\'es. Cette directive est surtout utilis\'ee \`a des fins de tests pour + simuler des petits volumes, mais elle peut aussi se r\'ev\'eler utile si voulez + limiter la taille de vos volumes, par exemple \`a 2 Go. Certains rares lecteurs + vraiment anciens ne signalent pas correctement lorsque la fin de la + cartouche est atteinte lors d'une op\'eration d'\'ecriture (Bien que j'aie lu des + choses au sujet de tels lecteurs, je n'en n'ai jamais rencontr\'e moi-m\^eme). Notez + que cette directive est obsol\`ete, rendue inutile par la + directive {\bf Maximum Volume Bytes} d\'efinie dans le fichier de configuration + du Director. + +\item [Maximum File Size = {\it size}] + \index[sd]{Maximum File Size} + \index[sd]{Directive!Maximum File Size} + Cette directive vous permet d'imposer une limite au poids des fichiers logiques + sur le volume. La valeur {\bf size} repr\'esente le nombre d'octets autoris\'es + par fichier. Une fois cette valeur atteinte, une marque de fin de fichier est + plac\'ee sur le volume et les donn\'ees suivantes sont plac\'ees dans un nouveau + fichier. Ce d\'ecoupage des longues s\'equences de donn\'ees en blocs plus petits + permet un positionnement plus rapide du lecteur au d\'ebut d'un flux de donn\'ees + et peut contribuer \`a pr\'evenir les erreurs de lecture sur la cartouche lors des + restaurations. La valeur par d\'efaut est 1 Go. + +\item [Block Positioning = {\it yes|no}] + \index[sd]{Block Positioning} + \index[sd]{Directive!Block Positioning} + Cette directive n'est pas utilis\'ee en fonctionnement normal (et n'a pas encore + \'et\'e test\'ee). Son r\^ole est d'enjoindre Bacula \`a ne plus utiliser le + positionnement par blocs lors de la lecture des cartouches. Ceci peut rendre + les op\'erations de restauration {\bf extr\`emement} lentes. Vous utiliserez cette + directive si vous avez \'ecrit vos cartouches avec Bacula en mode "taille de blocs + variable" tandis que votre lecteur \'etait en taille de blocs fixe. Si tout + fonctionne comme je l'esp\`ere, Bacula sera capable de relire vos cartouches. + +\item [Maximum Network Buffer Size = {\it bytes}] + \index[sd]{Maximum Network Buffer Size} + \index[sd]{Directive!Maximum Network Buffer Size} + Cette directive permet de sp\'ecifier la taille initiale du tampon r\'eseau \`a + utiliser avec le File Daemon. La valeur {\bf bytes} est la taille exprim\'ee + en octets. Cette valeur es appel\'ee \`a \^etre ajust\'ee \`a la baisse si elle est + trop importante, jusqu'\`a ce qu'elle soit accep\'ee par le syst\`eme d'exploitation. + Soyez circonspect dans l'usage de cette directive, car si vous utilisez une + valeur trop grande, elle sera diminu\'ee par incr\'ements de 521 octets jusqu'\`a + satisfaction du syst\`eme d'exploitation, ce qui peut n\'ecessiter un grand nombre + d'appels syst\`eme. La valeur par d\'efaut est 32 768 octets. + + La valeur par d\'efaut a \'et\'e choisie relativement importante, mais pas trop, + au cas ou vous transmettriez vos donn\'ees via Internet. Il est clair que sur + un r\'eseau local rapide, vous pouvez augmenter cette valeur et am\'eliorer les + performances. Par exemple, certains utilisateurs ont obtenu des facteurs + d'acc\'el\'eration de l'ordre de 5 \`a 10 en utilisant un tampon r\'eseau initial de + 65 536 octets. La plupart des utilisateurs indiquent que des valeurs plus + grandes ne semblent pas am\'eliorer les performances. Si vous voulez am\'eliorer + la viteese de vos sauvegardes, cette directive est probablement le meilleur + endroit pour exp\'erimenter. Vous voudrez probablement effectuer les + modifications correspondantes dans les fichiers de configuration de chacun + des File Daemons. + +\item [Maximum Spool Size = {\it bytes}] + \index[sd]{Maximum Spool Size} + \index[sd]{Directive!Maximum Spool Size} + Cette directive limite \`a la valeur sp\'ecifi\'ee (en octets) le volume occup\'e par + le tampon (NDT : spool) disque pour tous les jobs en ex\'ecution. Par d\'efaut, il n'y a + pas de limite. + +\item [Maximum Job Spool Size = {\it bytes}] + \index[sd]{Maximum Job Spool Size} + \index[sd]{Directive!Maximum Job Spool Size} + Cette directive limite \`a la valeur sp\'ecifi\'ee (en octets) le volume occup\'e par + le tampon disque pour chaque job. Par d\'efaut, il n'y a pas de limite. Cette + directive est apparue avel la version 1.37. + +\item [Spool Directory = {\it directory}] + \index[sd]{Spool Directory} + \index[sd]{Directive!Spool Directory} + Cette directive sp\'ecifie le nom du r\'epertoire \`a utiliser en tant que tampon + disque pour ce p\'eriph\'erique. Ce r\'epertoire est aussi utilis\'e pour stocker + les fichiers partiels lors de l'\'ecriture sur des supports qui requi\`erent + un montage (DVD). Le comportement par d\'efaut est d'utiliser le r\'epertoire + de travail de Bacula (working directory). + +\item [Maximum Part Size = {\it bytes}] + \index[sd]{Maximum Part Size} + \index[sd]{Directive!Maximum Part Size} + Cette directive pr\'ecise la taille maximale (en octets) d'un fichier partiel. Par d\'efaut, + il n'y a pas de limite. Cette directive est apparue avec la version 1.37. + + Si le p\'eriph\'erique requiert un montage, l'ordre de montage est transmis lorsque + cette valeur est atteinte. Dans ce cas, vous devez vous assurer d'avor suffisament + d'espace dans votre r\'epertoire tampon, faute de quoi vos donn\'ees resteront dans le + r\'epertoire tampon. + + Cette directive est ignor\'ee pour les lecteurs de bandes et les FIFO. + +\end{description} + +\section{P\'eriph\'eriques qui requi\`erent un montage (DVD)} +\index[general]{P\'eriph\'eriques qui requi\`erent un montage (DVD)} +\index[general]{DVD!P\'eriph\'eriques qui requi\`erent un montage} +\addcontentsline{toc}{section}{P\'eriph\'eriques qui requi\`erent un montage (DVD)} + +Toutes les directives d\'ecrites dans cette section sont impl\'ement\'ees dans Bacula +\`a partir de la version 1.37. + +A partir de la version 1.39.5, les directives "Requires Mount", "Mount Point", +"Mount Command", et "Unmount Command" s'appliquent aux syst\`emes de fichiers +amovibles tels que les p\'erih\'eriques USB, et plus seulement aux DVDs. + +\begin{description} + +\item [Requires Mount = {\it Yes|No}] + \index[sd]{Requires Mount} + \index[sd]{Directive!Requires Mount} + Cette directive doit \^etre \`a {\bf yes} pour les graveurs de DVDs, et \`a {\bf no} + pour tous les autres p\'eriph\'eriques (cartouches/fichiers). Elle indique si + le p\'eriph\'erique n\'ecessite d'\^etre mont\'e pour \^etre lu, et si un moyen particulier + doit \^etre employ\'e pour y \'ecrire. Si vous activez cette directive, vous devez aussi + d\'efinir les directives {\bf Mount Point}, {\bf Mount Command}, {\bf Unmount Command} + et {\bf Write Part Command}. + +\item [Mount Point = {\it directory}] + \index[sd]{Mount Point} + \index[sd]{Directive!Mount Point} + Cette directive sp\'ecifie le r\'epertoire o\`u le p\'eriph\'erique peut \^etre mont\'e. + (le point de montage) + +\item [Mount Command = {\it name-string}] + \index[sd]{Mount Command} + \index[sd]{Directive!Mount Command} + Cette directive sp\'ecifie la commande \`a ex\'ecuter pour monter le p\'eriph\'erique. + Avant l'ex\'ecution de la commande, \%a est remplac\'e par le p\'eriph\'erique de + stockage, et \%m par le point de montage (Mount Point). + + La plupart du temps, vous le d\'efinirez ainsi : + +\footnotesize +\begin{verbatim} + Mount Command = "/bin/mount -t iso9660 -o ro %a %m" +\end{verbatim} +\normalsize + +\item [Unmount Command = {\it name-string}] + \index[sd]{Unmount Command} + \index[sd]{Directive!Unmount Command} + Cette directive sp\'ecifie la commande \`a ex\'ecuter pour d\'emonter le p\'eriph\'erique. + Avant l'ex\'ecution de la commande, \%a est remplac\'e par le p\'eriph\'erique de + stockage, et \%m par le point de montage (Mount Point). + + La plupart du temps, vous le d\'efinirez ainsi : + +\footnotesize +\begin{verbatim} + Unmount Command = "/bin/umount %m" +\end{verbatim} +\normalsize + +\item [Write Part Command = {\it name-string}] + \index[sd]{Write Part Command} + \index[sd]{Directive!Write Part Command} + Cette directive sp\'ecifie la commande \`a ex\'ecuter pour \'ecrire une partition (NDT : Revoir cette partie, VO ci-dessous) + sur le p\'eriph\'erique. Avant l'ex\'ecution de la commande, \%a est remplac\'e par le p\'eriph\'erique de + stockage, \%m par le point de montage, \%e par 1 s'il s'agit de la premi\`ere + partition, 0 sinon, et \%v avec le nom de fichier de la partition courante. + + Pour un DVD, vous utiliserez la plupart du temps le script fourni {\bf dvd-handler} + comme suit : + +Command that must be executed to write a part to the device. Before the + command is executed, \%a is replaced with the Archive Device, \%m with the + Mount Point, \%e is replaced with 1 if we are writing the first part, + and with 0 otherwise, and \%v with the current part filename. + + For a DVD, you will most frequently specify the Bacula supplied {\bf + dvd-handler} script as follows: + +\footnotesize +\begin{verbatim} + Write Part Command = "/path/dvd-handler %a write %e %v" +\end{verbatim} +\normalsize + + O\`u {\bf /path} est le chemin vers votre r\'epertoire de scripts, et + dvd-handler est le script fourni avec Bacula. Cette commande est d\'ej\`a pr\'esente + quoique comment\'ee dans le fichier de configuration du Storage Daemon. Pour l'utiliser, + il vous suffit de supprimer le caract\`ere \#. + +\item [Free Space Command = {\it name-string}] + \index[sd]{Free Space Command} + \index[sd]{Directive!Free Space Command} + Cette directive sp\'ecifie la commande \`a ex\'ecuter pour contr\^oler l'espace disponible + sur le p\'eriph\'erique. Avant l'ex\'ecution de la commande, \%a est remplac\'e par le p\'eriph\'erique de + stockage, \%m par le point de montage, \%e par 1 s'il s'agit de la premi\`ere + partition, 0 sinon, et \%v avec le nom de fichier de la partition courante. + + Pour un DVD, vous utiliserez la plupart du temps le script fourni {\bf dvd-handler} + comme suit : + +\footnotesize +\begin{verbatim} + Free Space Command = "/path/dvd-handler %a free" +\end{verbatim} +\normalsize + + O\`u {\bf /path} est le chemin vers votre r\'epertoire de scripts, et + dvd-handler est le script fourni avec Bacula. Si vous voulez + sp\'ecifier votre propre commande, examinez le code de dvd-handler afin de + voir le type de retour attendu par Bacula. Cette commande est d\'ej\`a pr\'esente + quoique comment\'ee dans le fichier de configuration du Storage Daemon. Pour l'utiliser, + il vous suffit de supprimer le caract\`ere \#. + + Si vous n'utilisez pas cette directive, Bacula s'attendra \`a ce qu'il y ait + toujours de la place dur le p\'eriph\'erique. + +\end{description} + +%% This pulls in the Autochanger resource from another file. +\label{AutochangerRes} +\label{AutochangerResource1} +\input{autochangerres} + + +\section{Possibilit\'es} +\index[general]{Possibilit\'es} +\addcontentsline{toc}{section}{Possibilit\'es} + +\begin{description} + +\item [Label media = {\it Yes|No}] + \index[sd]{Label media} + \index[sd]{Directive!Label media} + Si cette directive est activ\'ee ({\bf Yes}), alors ce p\'eriph\'erique est + habilit\'e \`a \'etiqueter les media libres sans ordre explicite de l'op\'erateur. + Ceci est r\'ealis\'e selon un algorithme interne et suivant le format + d\'efini par l'enregistrement \ilink{Label Format}{Label} de chaque + ressource Pool. Si cette directive est \`a {\bf No} (valeur par d\'efaut), + Bacula n'\'etiquette les cartouches que sur instruction expresse de + l'op\'erateur (commande {\bf label} de la Console) ou lorsqu'une cartouche + a \'et\'e recycl\'ee. Cette fonctionnalit\'e est plus utile dans le cas de sauvegardes + sur disque qu'avec des cartouches. + +\item [Automatic mount = {\it Yes|No}] + \index[sd]{Automatic mount} + \index[sd]{Directive!Automatic mount} + Si cette directive est activ\'ee (c'est le cas par d\'efaut), le Storage Daemon + est autoris\'e \`a examiner le p\'eriph\'erique afin de d\'eterminer s'il contient + un volume \'etiquet\'e Bacula. Ceci est alors fait au d\'emarrage du {\it daemon}, + et au d\'ebut de chaque job. Cette directive est particuli\`erement importante + si vous avez sp\'ecifi\'e {\bf Always Open = no} car elle permet \`a + Bacula de tenter de lire le p\'eriph\'erique avant de demander \`a l'op\'erateur + de monter une cartouche. Notez cependant que la cartouche doit \^etre + mont\'ee avant le lancement du job. + +\end{description} + +\section{La ressource Messages} +\label{MessagesResource1} +\index[general]{Ressource!Messages} +\index[general]{Ressource Messages} +\addcontentsline{toc}{section}{Resource Messages} + +Pour une description de la ressource Messages, veuillez consulter +le chapitre \ilink{La ressource Messages}{_ChapterStart15} de ce +manuel. + +\section{Un exemple de fichier de configuration du Storage Daemon} +\label{SampleConfiguration} +\index[general]{Fichier!Exemple configuration Storage Daemon} +\index[general]{Exemple fichier configuration Storage Daemon} +\addcontentsline{toc}{section}{Exemple fichier configuration Storage Daemon} + +Voici un exemple de fichier de configuration du Storage Daemon : + +\footnotesize +\begin{verbatim} +# +# Default Bacula Storage Daemon Configuration file +# +# For Bacula release 1.37.2 (07 July 2005) -- gentoo 1.4.16 +# +# You may need to change the name of your tape drive +# on the "Archive Device" directive in the Device +# resource. If you change the Name and/or the +# "Media Type" in the Device resource, please ensure +# that bacula-dir.conf has corresponding changes. +# +Storage { # definition of myself + Name = rufus-sd + Address = rufus + WorkingDirectory = "$HOME/bacula/bin/working" + Pid Directory = "$HOME/bacula/bin/working" + Maximum Concurrent Jobs = 20 +} +# +# List Directors who are permitted to contact Storage daemon +# +Director { + Name = rufus-dir + Password = "ZF9Ctf5PQoWCPkmR3s4atCB0usUPg+vWWyIo2VS5ti6k" +} +# +# Restricted Director, used by tray-monitor to get the +# status of the storage daemon +# +Director { + Name = rufus-mon + Password = "9usxgc307dMbe7jbD16v0PXlhD64UVasIDD0DH2WAujcDsc6" + Monitor = yes +} +# +# Devices supported by this Storage daemon +# To connect, the Director's bacula-dir.conf must have the +# same Name and MediaType. +# +Autochanger { + Name = Autochanger + Device = Drive-1 + Device = Drive-2 + Changer Command = "/home/kern/bacula/bin/mtx-changer %c %o %S %a %d" + Changer Device = /dev/sg0 +} + +Device { + Name = Drive-1 # + Drive Index = 0 + Media Type = DLT-8000 + Archive Device = /dev/nst0 + AutomaticMount = yes; # when device opened, read it + AlwaysOpen = yes; + RemovableMedia = yes; + RandomAccess = no; + AutoChanger = yes + Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'" +} + +Device { + Name = Drive-2 # + Drive Index = 1 + Media Type = DLT-8000 + Archive Device = /dev/nst1 + AutomaticMount = yes; # when device opened, read it + AlwaysOpen = yes; + RemovableMedia = yes; + RandomAccess = no; + AutoChanger = yes + Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'" +} + +Device { + Name = "HP DLT 80" + Media Type = DLT8000 + Archive Device = /dev/nst0 + AutomaticMount = yes; # when device opened, read it + AlwaysOpen = yes; + RemovableMedia = yes; +} +#Device { +# Name = SDT-7000 # +# Media Type = DDS-2 +# Archive Device = /dev/nst0 +# AutomaticMount = yes; # when device opened, read it +# AlwaysOpen = yes; +# RemovableMedia = yes; +#} +#Device { +# Name = Floppy +# Media Type = Floppy +# Archive Device = /mnt/floppy +# RemovableMedia = yes; +# Random Access = Yes; +# AutomaticMount = yes; # when device opened, read it +# AlwaysOpen = no; +#} +#Device { +# Name = FileStorage +# Media Type = File +# Archive Device = /tmp +# LabelMedia = yes; # lets Bacula label unlabeled media +# Random Access = Yes; +# AutomaticMount = yes; # when device opened, read it +# RemovableMedia = no; +# AlwaysOpen = no; +#} +#Device { +# Name = "NEC ND-1300A" +# Media Type = DVD +# Archive Device = /dev/hda +# LabelMedia = yes; # lets Bacula label unlabeled media +# Random Access = Yes; +# AutomaticMount = yes; # when device opened, read it +# RemovableMedia = yes; +# AlwaysOpen = no; +# MaximumPartSize = 800M; +# RequiresMount = yes; +# MountPoint = /mnt/cdrom; +# MountCommand = "/bin/mount -t iso9660 -o ro %a %m"; +# UnmountCommand = "/bin/umount %m"; +# SpoolDirectory = /tmp/backup; +# WritePartCommand = "/etc/bacula/dvd-handler %a write %e %v" +# FreeSpaceCommand = "/etc/bacula/dvd-handler %a free" +#} +# +# A very old Exabyte with no end of media detection +# +#Device { +# Name = "Exabyte 8mm" +# Media Type = "8mm" +# Archive Device = /dev/nst0 +# Hardware end of medium = No; +# AutomaticMount = yes; # when device opened, read it +# AlwaysOpen = Yes; +# RemovableMedia = yes; +#} +# +# Send all messages to the Director, +# mount messages also are sent to the email address +# +Messages { + Name = Standard + director = rufus-dir = all + operator = root = mount +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/install/translate_images.pl b/docs/manuals/fr/install/translate_images.pl new file mode 100755 index 00000000..c7225118 --- /dev/null +++ b/docs/manuals/fr/install/translate_images.pl @@ -0,0 +1,185 @@ +#!/usr/bin/perl -w +# +use strict; + +# Used to change the names of the image files generated by latex2html from imgxx.png +# to meaningful names. Provision is made to go either from or to the meaningful names. +# The meaningful names are obtained from a file called imagename_translations, which +# is generated by extensions to latex2html in the make_image_file subroutine in +# bacula.perl. + +# Opens the file imagename_translations and reads the contents into a hash. +# The hash is creaed with the imgxx.png files as the key if processing TO +# meaningful filenames, and with the meaningful filenames as the key if +# processing FROM meaningful filenames. +# Then opens the html file(s) indicated in the command-line arguments and +# changes all image references according to the translations described in the +# above file. Finally, it renames the image files. +# +# Original creation: 3-27-05 by Karl Cunningham. +# Modified 5-21-05 to go FROM and TO meaningful filenames. +# +my $TRANSFILE = "imagename_translations"; +my $path; + +# Loads the contents of $TRANSFILE file into the hash referenced in the first +# argument. The hash is loaded to translate old to new if $direction is 0, +# otherwise it is loaded to translate new to old. In this context, the +# 'old' filename is the meaningful name, and the 'new' filename is the +# imgxx.png filename. It is assumed that the old image is the one that +# latex2html has used as the source to create the imgxx.png filename. +# The filename extension is taken from the file +sub read_transfile { + my ($trans,$direction) = @_; + + if (!open IN,"<$path$TRANSFILE") { + print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n"; + print " Image filename translation aborted\n\n"; + exit 0; + } + + while () { + chomp; + my ($new,$old) = split(/\001/); + + # Old filenames will usually have a leading ./ which we don't need. + $old =~ s/^\.\///; + + # The filename extension of the old filename must be made to match + # the new filename because it indicates the encoding format of the image. + my ($ext) = $new =~ /(\.[^\.]*)$/; + $old =~ s/\.[^\.]*$/$ext/; + if ($direction == 0) { + $trans->{$new} = $old; + } else { + $trans->{$old} = $new; + } + } + close IN; +} + +# Translates the image names in the file given as the first argument, according to +# the translations in the hash that is given as the second argument. +# The file contents are read in entirely into a string, the string is processed, and +# the file contents are then written. No particular care is taken to ensure that the +# file is not lost if a system failure occurs at an inopportune time. It is assumed +# that the html files being processed here can be recreated on demand. +# +# Links to other files are added to the %filelist for processing. That way, +# all linked files will be processed (assuming they are local). +sub translate_html { + my ($filename,$trans,$filelist) = @_; + my ($contents,$out,$this,$img,$dest); + my $cnt = 0; + + # If the filename is an external link ignore it. And drop any file:// from + # the filename. + $filename =~ /^(http|ftp|mailto)\:/ and return 0; + $filename =~ s/^file\:\/\///; + # Load the contents of the html file. + if (!open IF,"<$path$filename") { + print "WARNING: Cannot open $path$filename for reading\n"; + print " Image Filename Translation aborted\n\n"; + exit 0; + } + + while () { + $contents .= $_; + } + close IF; + + # Now do the translation... + # First, search for an image filename. + while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) { + $contents = $'; + $out .= $` . $&; + + # The next thing is an image name. Get it and translate it. + $contents =~ /^(.*?)\"/s; + $contents = $'; + $this = $&; + $img = $1; + # If the image is in our list of ones to be translated, do it + # and feed the result to the output. + $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img})); + $out .= $this; + } + $out .= $contents; + + # Now send the translated text to the html file, overwriting what's there. + open OF,">$path$filename" or die "Cannot open $path$filename for writing\n"; + print OF $out; + close OF; + + # Now look for any links to other files and add them to the list of files to do. + while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) { + $out = $'; + $dest = $1; + # Drop an # and anything after it. + $dest =~ s/\#.*//; + $filelist->{$dest} = '' if $dest; + } + return $cnt; +} + +# REnames the image files spefified in the %translate hash. +sub rename_images { + my $translate = shift; + my ($response); + + foreach (keys(%$translate)) { + if (! $translate->{$_}) { + print " WARNING: No destination Filename for $_\n"; + } else { + $response = `mv -f $path$_ $path$translate->{$_} 2>&1`; + $response and print "ERROR from system $response\n"; + } + } +} + +################################################# +############# MAIN ############################# +################################################ + +# %filelist starts out with keys from the @ARGV list. As files are processed, +# any links to other files are added to the %filelist. A hash of processed +# files is kept so we don't do any twice. + +# The first argument must be either --to_meaningful_names or --from_meaningful_names + +my (%translate,$search_regex,%filelist,%completed,$thisfile); +my ($cnt,$direction); + +my $arg0 = shift(@ARGV); +$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or + die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n"; + +$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1; + +(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n"; + +# Use the first argument to get the path to the file of translations. +my $tmp = $ARGV[0]; +($path) = $tmp =~ /(.*\/)/; +$path = '' unless $path; + +read_transfile(\%translate,$direction); + +foreach (@ARGV) { + # Strip the path from the filename, and use it later on. + if (s/(.*\/)//) { + $path = $1; + } else { + $path = ''; + } + $filelist{$_} = ''; + + while ($thisfile = (keys(%filelist))[0]) { + $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile})); + delete($filelist{$thisfile}); + $completed{$thisfile} = ''; + } + print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n"; +} + +rename_images(\%translate); diff --git a/docs/manuals/fr/install/update_version b/docs/manuals/fr/install/update_version new file mode 100755 index 00000000..5c2e0092 --- /dev/null +++ b/docs/manuals/fr/install/update_version @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/install/update_version.in b/docs/manuals/fr/install/update_version.in new file mode 100644 index 00000000..2766245f --- /dev/null +++ b/docs/manuals/fr/install/update_version.in @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/install/version.tex b/docs/manuals/fr/install/version.tex new file mode 100644 index 00000000..82d910aa --- /dev/null +++ b/docs/manuals/fr/install/version.tex @@ -0,0 +1 @@ +2.3.6 (04 November 2007) diff --git a/docs/manuals/fr/install/version.tex.in b/docs/manuals/fr/install/version.tex.in new file mode 100644 index 00000000..ff66dfc6 --- /dev/null +++ b/docs/manuals/fr/install/version.tex.in @@ -0,0 +1 @@ +@VERSION@ (@DATE@) diff --git a/docs/manuals/fr/problems/Makefile b/docs/manuals/fr/problems/Makefile new file mode 100644 index 00000000..55cb58c6 --- /dev/null +++ b/docs/manuals/fr/problems/Makefile @@ -0,0 +1,136 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=problems + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Problem Resolution Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Proble*.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + @rm -f ${DOC}i-*.tex + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/problems/Makefile.in b/docs/manuals/fr/problems/Makefile.in new file mode 100644 index 00000000..55cb58c6 --- /dev/null +++ b/docs/manuals/fr/problems/Makefile.in @@ -0,0 +1,136 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=problems + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Problem Resolution Guide" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Proble*.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + @rm -f ${DOC}i-*.tex + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/problems/check_tex.pl b/docs/manuals/fr/problems/check_tex.pl new file mode 100755 index 00000000..e12d51be --- /dev/null +++ b/docs/manuals/fr/problems/check_tex.pl @@ -0,0 +1,152 @@ +#!/usr/bin/perl -w +# Finds potential problems in tex files, and issues warnings to the console +# about what it finds. Takes a list of files as its only arguments, +# and does checks on all the files listed. The assumption is that these are +# valid (or close to valid) LaTeX files. It follows \include statements +# recursively to pick up any included tex files. +# +# +# +# Currently the following checks are made: +# +# -- Multiple hyphens not inside a verbatim environment (or \verb). These +# should be placed inside a \verb{} contruct so they will not be converted +# to single hyphen by latex and latex2html. + + +# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com +# +# + +use strict; + +# The following builds the test string to identify and change multiple +# hyphens in the tex files. Several constructs are identified but only +# multiple hyphens are changed; the others are fed to the output +# unchanged. +my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{ +my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{ +my $c = '\\s*\\}'; # closing curly brace + +# This captures entire verbatim environments. These are passed to the output +# file unchanged. +my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c; + +# This captures \verb{..{ constructs. They are passed to the output unchanged. +my $verb = '\\\\verb\\*?(.).*?\\1'; + +# This captures multiple hyphens with a leading and trailing space. These are not changed. +my $hyphsp = '\\s\\-{2,}\\s'; + +# This identifies other multiple hyphens. +my $hyphens = '\\-{2,}'; + +# This identifies \hyperpage{..} commands, which should be ignored. +my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}'; + +# This builds the actual test string from the above strings. +#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens"; +my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens"; + + +sub get_includes { + # Get a list of include files from the top-level tex file. The first + # argument is a pointer to the list of files found. The rest of the + # arguments is a list of filenames to check for includes. + my $files = shift; + my ($fileline,$includefile,$includes); + + while (my $filename = shift) { + # Get a list of all the html files in the directory. + open my $if,"<$filename" or die "Cannot open input file $filename\n"; + $fileline = 0; + $includes = 0; + while (<$if>) { + chomp; + $fileline++; + # If a file is found in an include, process it. + if (($includefile) = /\\include\s*\{(.*?)\}/) { + $includes++; + # Append .tex to the filename + $includefile .= '.tex'; + + # If the include file has already been processed, issue a warning + # and don't do it again. + my $found = 0; + foreach (@$files) { + if ($_ eq $includefile) { + $found = 1; + last; + } + } + if ($found) { + print "$includefile found at line $fileline in $filename was previously included\n"; + } else { + # The file has not been previously found. Save it and + # recursively process it. + push (@$files,$includefile); + get_includes($files,$includefile); + } + } + } + close IF; + } +} + + +sub check_hyphens { + my (@files) = @_; + my ($filedata,$this,$linecnt,$before); + + # Build the test string to check for the various environments. + # We only do the conversion if the multiple hyphens are outside of a + # verbatim environment (either \begin{verbatim}...\end{verbatim} or + # \verb{--}). Capture those environments and pass them to the output + # unchanged. + + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # Set up to process the file data. + $linecnt = 1; + + # Go through the file data from beginning to end. For each match, save what + # came before it and what matched. $filedata now becomes only what came + # after the match. + # Chech the match to see if it starts with a multiple-hyphen. If so + # warn the user. Keep track of line numbers so they can be output + # with the warning message. + while ($filedata =~ /$teststr/os) { + $this = $&; + $before = $`; + $filedata = $'; + $linecnt += $before =~ tr/\n/\n/; + + # Check if the multiple hyphen is present outside of one of the + # acceptable constructs. + if ($this =~ /^\-+/) { + print "Possible unwanted multiple hyphen found in line ", + "$linecnt of file $file\n"; + } + $linecnt += $this =~ tr/\n/\n/; + } + } +} +################################################################## +# MAIN #### +################################################################## + +my (@includes,$cnt); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +get_includes(\@includes,@ARGV); + +check_hyphens(@includes); diff --git a/docs/manuals/fr/problems/do_echo b/docs/manuals/fr/problems/do_echo new file mode 100644 index 00000000..04b9f79a --- /dev/null +++ b/docs/manuals/fr/problems/do_echo @@ -0,0 +1,6 @@ +# +# Avoid that @VERSION@ and @DATE@ are changed by configure +# This file is sourced by update_version +# +echo "s%@VERSION@%${VERSION}%g" >${out} +echo "s%@DATE@%${DATE}%g" >>${out} diff --git a/docs/manuals/fr/problems/faq.tex b/docs/manuals/fr/problems/faq.tex new file mode 100644 index 00000000..df0f0554 --- /dev/null +++ b/docs/manuals/fr/problems/faq.tex @@ -0,0 +1,876 @@ +%% +%% +% TODO: maybe merge all this FAQ in with the appropriate section? +% TODO: and use detailed indexing to help reader + +\chapter{Bacula Frequently Asked Questions} +\label{FaqChapter} +\index[general]{Questions!Bacula Frequently Asked } +\index[general]{Bacula Frequently Asked Questions } + +These are questions that have been submitted over time by the +Bacula users. The following +FAQ is very useful, but it is not always up to date +with newer information, so after reading it, if you don't find what you +want, you might try the Bacula wiki maintained by Frank Sweetser, which +contains more than just a FAQ: +\elink{http://wiki.bacula.org}{\url{http://wiki.bacula.org}} +or go directly to the FAQ at: +\elink{http://wiki.bacula.org/doku.php?id=faq} +{\url{http://wiki.bacula.org/doku.php?id=faq}}. + +Please also see +\ilink{the bugs section}{BugsChapter} of this document for a list +of known bugs and solutions. + +\begin{description} +\label{what} +\section{What is Bacula?} +\item [What is {\bf Bacula}? ] + \index[general]{What is Bacula? } + {\bf Bacula} is a network backup and restore program. + +\section{Does Bacula support Windows?} +\item [Does Bacula support Windows?] +\index[general]{Does Bacula support Windows? } + Yes, Bacula compiles and runs on Windows machines (Win98, WinMe, WinXP, + WinNT, Win2003, and Win2000). We provide a binary version of the Client + (bacula-fd), but have not tested the Director nor the Storage daemon. + Note, Win95 is no longer supported because it doesn't have the + GetFileAttributesExA API call. + + +\label{lang} +\section{What language is Bacula written in?} +\item [What language is Bacula written in?] +\index[general]{What language is Bacula written in? } + It is written in C++, but it is mostly C code using only a limited set of + the C++ extensions over C. Thus Bacula is completely compiled using the + C++ compiler. There are several modules, including the Win32 interface, that + are written using the object oriented C++ features. Over time, we are slowly + adding a larger subset of C++. + +\label{run} +\section{On what machines does Bacula run?} +\item [On what machines does Bacula run? ] + \index[general]{On what machines does Bacula run? } + {\bf Bacula} builds and executes on Red Hat Linux (versions RH7.1-RHEL + 4.0, Fedora, SuSE, Gentoo, Debian, Mandriva, ...), FreeBSD, Solaris, + Alpha, SGI (client), NetBSD, OpenBSD, Mac OS X (client), and Win32. + + Bacula has been my only backup tool for over seven years backing up 8 + machines nightly (6 Linux boxes running SuSE, previously + Red Hat and Fedora, a WinXP machine, and a WinNT machine). + + +\label{stable} +\section{Is Bacula Stable?} +\item [Is Bacula Stable? ] +\index[general]{Is Bacula Stable? } + Yes, it is remarkably stable, but remember, there are still a lot of + unimplemented or partially implemented features. With a program of this + size (150,000+ lines of C++ code not including the SQL programs) there + are bound to be bugs. The current test environment (a twisted pair + local network and a HP DLT backup tape) is not exactly ideal, so + additional testing on other sites is necessary. The File daemon has + never crashed -- running months at a time with no intervention. The + Storage daemon is remarkably stable with most of the problems arising + during labeling or switching tapes. Storage daemon crashes are rare + but running multiple drives and simultaneous jobs sometimes (rarely) + problems. + The Director, given the multitude of functions it fulfills is also + relatively stable. In a production environment, it rarely if ever + crashes. Of the three daemons, the Director is the most prone to having + problems. Still, it frequently runs several months with no problems. + + There are a number of reasons for this stability. + + \begin{enumerate} + \item The program is constantly checking the chain of allocated + memory buffers to ensure that no overruns have occurred. \\ + \item All memory leaks (orphaned buffers) are reported each time the + program terminates.\\ + \item Any signal (segmentation fault, ...) generates a + traceback that is emailed to the developer. This permits quick + resolution of bugs even if they only show up rarely in a production + system.\\ + \item There is a reasonably comprehensive set of regression tests + that avoids re-creating the most common errors in new versions of + Bacula. + \end{enumerate} + +\label{AuthorizationErrors} +\section{I'm Getting Authorization Errors. What is Going On? } +\item [I'm Getting Authorization Errors. What is Going On? ] +\index[general]{Authorization Errors} +\index[general]{Concurrent Jobs} + For security reasons, Bacula requires that both the File daemon and the + Storage daemon know the name of the Director as well as its password. As a + consequence, if you change the Director's name or password, you must make + the corresponding change in the Storage daemon's and in the File daemon's + configuration files. + + During the authorization process, the Storage daemon and File daemon + also require that the Director authenticates itself, so both ends + require the other to have the correct name and password. + + If you have edited the conf files and modified any name or any password, + and you are getting authentication errors, then your best bet is to go + back to the original conf files generated by the Bacula installation + process. Make only the absolutely necessary modifications to these + files -- e.g. add the correct email address. Then follow the + instructions in the \ilink{ Running Bacula}{TutorialChapter} chapter of + this manual. You will run a backup to disk and a restore. Only when + that works, should you begin customization of the conf files. + + Another reason that you can get authentication errors is if you are + running Multiple Concurrent Jobs in the Director, but you have not set + them in the File daemon or the Storage daemon. Once you reach their + limit, they will reject the connection producing authentication (or + connection) errors. + + If you are having problems connecting to a Windows machine that + previously worked, you might try restarting the Bacula service since + Windows frequently encounters networking connection problems. + + Some users report that authentication fails if there is not a proper + reverse DNS lookup entry for the machine. This seems to be a + requirement of gethostbyname(), which is what Bacula uses to translate + names into IP addresses. If you cannot add a reverse DNS entry, or you + don't know how to do so, you can avoid the problem by specifying an IP + address rather than a machine name in the appropriate Bacula conf file. + + Here is a picture that indicates what names/passwords in which + files/Resources must match up: + + \includegraphics{./Conf-Diagram.eps} + + In the left column, you will find the Director, Storage, and Client + resources, with their names and passwords -- these are all in {\bf + bacula-dir.conf}. The right column is where the corresponding values + should be found in the Console, Storage daemon (SD), and File daemon (FD) + configuration files. + + Another thing to check is to ensure that the Bacula component you are + trying to access has {\bf Maximum Concurrent Jobs} set large enough to + handle each of the Jobs and the Console that want to connect + simultaneously. Once the maximum connections has been reached, each + Bacula component will reject all new connections. + + Finally, make sure you have no {\bf hosts.allow} or {\bf hosts.deny} + file that is not permitting access to the site trying to connect. + +\label{AccessProblems} +\section{Bacula Runs Fine but Cannot Access a Client on a Different Machine. + Why? } +\item [Bacula Runs Fine but Cannot Access a Client on a Different Machine. + Why? ] +\index[general]{Cannot Access a Client} + There are several reasons why Bacula could not contact a client on a + different machine. They are: + +\begin{itemize} +\item It is a Windows Client, and the client died because of an improper + configuration file. Check that the Bacula icon is in the system tray and the + the menu items work. If the client has died, the icon will disappear only + when you move the mouse over the icon. +\item The Client address or port is incorrect or not resolved by DNS. See if + you can ping the client machine using the same address as in the Client + record. +\item You have a firewall, and it is blocking traffic on port 9102 between + the Director's machine and the Client's machine (or on port 9103 between the + Client and the Storage daemon machines). +\item Your password or names are not correct in both the Director and the + Client machine. Try configuring everything identical to how you run the + client on the same machine as the Director, but just change the Address. If + that works, make the other changes one step at a time until it works. +\item You may also be having problems between your File daemon and your + Storage daemon. The name you use in the Storage resource of your + Director's conf file must be known (resolvable) by the File daemon, + because it is passed symbolically to the File daemon, which then + resolves it to get an IP address used to contact the Storage daemon. +\item You may have a {\bf hosts.allow} or {\bf hosts.deny} file that is + not permitting access. +\end{itemize} + +\label{startover} +\section{My Catalog is Full of Test Runs, How Can I Start Over?} +\item [My Catalog is Full of Test Runs, How Can I Start Over? ] + \index[general]{My Catalog is Full of Test Runs, How Can I Start Over? } + If you are using MySQL do the following: + +\footnotesize +\begin{verbatim} + cd /src/cats + ./drop_mysql_tables + ./make_mysql_tables + +\end{verbatim} +\normalsize + +If you are using SQLite, do the following: + +\footnotesize +\begin{verbatim} + Delete bacula.db from your working directory. + cd /src/cats + ./drop_sqlite_tables + ./make_sqlite_tables + +\end{verbatim} +\normalsize + +Then write an EOF on each tape you used with {\bf Bacula} using: + +\footnotesize +\begin{verbatim} +mt -f /dev/st0 rewind +mt -f /dev/st0 weof +\end{verbatim} +\normalsize + +where you need to adjust the device name for your system. + +\label{restorehang} +\section{I Run a Restore Job and Bacula Hangs. What do I do?} +\item [I Run a Restore Job and Bacula Hangs. What do I do?] +\index[general]{I Run a Restore Job and Bacula Hangs. What do I do? } + On Bacula version 1.25 and prior, it expects you to have the correct + tape mounted prior to a restore. On Bacula version 1.26 and higher, it + will ask you for the tape, and if the wrong one is mounted, it will + inform you. + + If you have previously done an {\bf unmount} command, all Storage daemon + sessions (jobs) will be completely blocked from using the drive + unmounted, so be sure to do a {\bf mount} after your unmount. If in + doubt, do a second {\bf mount}, it won't cause any harm. + +\label{windowstart} +\section{I Cannot Get My Windows Client to Start Automatically? } +\item [I Cannot Get My Windows Client to Start Automatically? ] +\index[general]{Windows Auto Start} + You are probably having one of two problems: either the Client is dying + due to an incorrect configuration file, or you didn't do the + Installation commands necessary to install it as a Windows Service. + + For the first problem, see the next FAQ question. For the second + problem, please review the \ilink{ Windows Installation + instructions}{Win32Chapter} in this manual. + +\label{windowsdie} +\section{My Windows Client Immediately Dies When I Start It} +\item [My Windows Client Immediately Dies When I Start It] +\index[general]{Windows Client Dies} +The most common problem is either that the configuration file is not where +it expects it to be, or that there is an error in the configuration file. +You must have the configuration file in {\bf +c:\textbackslash{}bacula\textbackslash{}bin\textbackslash{}bacula-fd.conf}. + +To {\bf see} what is going on when the File daemon starts on Windows, do the +following: + +\footnotesize +\begin{verbatim} + Start a DOS shell Window. + cd c:\bacula\bin + bacula-fd -d100 -c c:\bacula\bin\bacula-fd.conf + +\end{verbatim} +\normalsize + +This will cause the FD to write a file {\bf bacula.trace} in the current +directory, which you can examine and thereby determine the problem. + +\label{scroll} +\item [When I Start the Console, the Error Messages Fly By. How can I see + them? ] +\index[general]{Error Messages} + Either use a shell window with a scroll bar, or use the gnome-console. + In any case, you probably should be logging all output to a file, and + then you can simply view the file using an editor or the {\bf less} + program. To log all output, I have the following in my Director's + Message resource definition: + +\footnotesize +\begin{verbatim} + append = "/home/kern/bacula/bin/log" = all, !skipped + +\end{verbatim} +\normalsize + +Obviously you will want to change the filename to be appropriate for your +system. + +\label{nobackup} +\section{My backups are not working on my Windows + Client. What should I do?} +\item [I didn't realize that the backups were not working on my Windows + Client. What should I do? ] +\index[general]{Backups Failing} +You should be sending yourself an email message for each job. This will avoid +the possibility of not knowing about a failed backup. To do so put something +like: + +\footnotesize +\begin{verbatim} + Mail = yourname@yourdomain = all, !skipped + +\end{verbatim} +\normalsize + +in your Director's message resource. You should then receive one email for +each Job that ran. When you are comfortable with what is going on (it took +me 9 months), you might change that to: + +\footnotesize +\begin{verbatim} + MailOnError = yourname@yourdomain = all, !skipped + +\end{verbatim} +\normalsize + +then you only get email messages when a Job errors as is the case for your +Windows machine. + +You should also be logging the Director's messages, please see the previous +FAQ for how to do so. + +\label{sched} +\section{All my Jobs are scheduled for the same time. Will this cause + problems?} +\item [All my Jobs are scheduled for the same time. Will this cause + problems? ] +\index[general]{Schedule problems} + No, not at all. Bacula will schedule all the Jobs at the same time, but + will run them one after another unless you have increased the number of + simultaneous jobs in the configuration files for the Director, the File + daemon, and the Storage daemon. The appropriate configuration record is + {\bf Maximum Concurrent Jobs = nn}. At the current time, we recommend + that you leave this set to {\bf 1} for the Director. + +\label{disk} +\section{Can Bacula Backup My System To Files instead of Tape?} +\item [Can Bacula Backup My System To Files instead of Tape? ] +\index[general]{Backup to Disk} + Yes, in principle, Bacula can backup to any storage medium as long as + you have correctly defined that medium in the Storage daemon's Device + resource. For an example of how to backup to files, please see the + \ilink{Pruning Example}{PruningExample} in the Recycling chapter of this + manual. Also, there is a whole chapter devoted to \ilink{Basic Volume + Management}{DiskChapter}. This chapter was originally written to + explain how to write to disk, but was expanded to include volume + management. It is, however, still quite a good chapter to read. + +\label{testbackup} +\section{Can I use a dummy device to test the backup?} + Yes, to have a {\sl Virtual} device which just consumes data, you can use a + FIFO device (see \ilink{Stored configuration}{SetupFifo}). + It's useful to test a backup. +\footnotesize +\begin{verbatim} +Device { + Name = NULL + Media Type = NULL + Device Type = Fifo + Archive Device = /dev/null + LabelMedia = yes + Random Access = no + AutomaticMount = no + RemovableMedia = no + MaximumOpenWait = 60 + AlwaysOpen = no +} +\end{verbatim} +\normalsize + +\label{bigfiles} +\section{Can Bacula Backup and Restore Files Bigger than 2 Gigabytes?} +\item [Can Bacula Backup and Restore Files Bigger than 2 Gigabytes?] +\index[general]{Large file support} +If your operating system permits it, and you are running Bacula version +1.26 or later, the answer is yes. To the best of our knowledge all client +system supported by Bacula can handle files bigger 2 Gigabytes. + +\label{cancel} +\section{I want to stop a job.} +%% Is there a better way than "./bacula stop" to stop it?} +\item [I Started A Job then Decided I Really Did Not Want to Run It. Is + there a better way than {\bf ./bacula stop} to stop it?] +\index[general]{Cancelling jobs} + Yes, you normally should use the Console command {\bf cancel} to cancel + a Job that is either scheduled or running. If the Job is scheduled, it + will be marked for cancellation and will be canceled when it is + scheduled to start. If it is running, it will normally terminate after + a few minutes. If the Job is waiting on a tape mount, you may need to + do a {\bf mount} command before it will be canceled. + +\label{trademark} +\section{Why have You Trademarked the Name Bacula?} +\item [Why have You Trademarked the Name + Bacula\raisebox{.6ex}{{\footnotesize \textsuperscript{\textregistered}}}?] +\index[general]{Bacula Trademark} +We have trademarked the name Bacula to ensure that all media written by any +program named Bacula will always be compatible. Anyone may use the name +Bacula, even in a derivative product as long as it remains totally compatible +in all respects with the program defined here. + +\label{docversion} +\section{Why is the Online Document for Version 1.39 but the Released Version is 1.38?} +\item [Why is the Online Document for Version 1.39 of Bacula when the + Current Version is 1.38?] +\index[general]{Multiple manuals} +As Bacula is being developed, the document is also being enhanced, more +often than not it has clarifications of existing features that can be very +useful to our users, so we publish the very latest document. Fortunately +it is rare that there are confusions with new features. + +If you want to read a document that pertains only to a specific version, +please use the one distributed in the source code. The web site also has +online versions of both the released manual and the current development +manual. + +\label{sure} +\section{Does Bacula really save and restore all files?} +\item [How Can I Be Sure that Bacula Really Saves and Restores All Files? ] +\index[general]{Checking Restores} + It is really quite simple, but took me a while to figure + out how to "prove" it. First make a Bacula Rescue disk, see the + \ilink{Disaster Recovery Using Bacula}{RescueChapter} chapter + of this manual. + Second, you run a full backup of all your files on all partitions. + Third, you run an Verify InitCatalog Job on the same FileSet, which + effectively makes a record of all the files on your system. Fourth, you + run a Verify Catalog job and assure yourself that nothing has changed + (well, between an InitCatalog and Catalog one doesn't expect anything). + Then do the unthinkable, write zeros on your MBR (master boot record) + wiping out your hard disk. Now, restore your whole system using your + Bacula Rescue disk and the Full backup you made, and finally re-run the + Verify Catalog job. You will see that with the exception of the + directory modification and access dates and the files changed during the + boot, your system is identical to what it was before you wiped your hard + disk. + Alternatively you could do the wiping and restoring to another computer + of the same type. + +\label{upgrade} +\section{I want an Incremental but Bacula runs it as a Full backup. Why?} +\item [I did a Full backup last week, but now in running an Incremental, + Bacula says it did not find a FULL backup, so it did a FULL backup. Why?] +\index[general]{FULL backup not found} + Before doing an Incremental or a Differential + backup, Bacula checks to see if there was a prior Full backup of the + same Job that terminated successfully. If so, it uses the date that + full backup started as the time for comparing if files have changed. If + Bacula does not find a successful full backup, it proceeds to do one. + Perhaps you canceled the full backup, or it terminated in error. In + such cases, the full backup will not be successful. You can check by + entering {\bf list jobs} and look to see if there is a prior Job with + the same Name that has Level F and JobStatus T (normal termination). + + Another reason why Bacula may not find a suitable Full backup is that + every time you change the FileSet, Bacula will require a new Full + backup. This is necessary to ensure that all files are properly backed + up in the case where you have added more files to the FileSet. + Beginning with version 1.31, the FileSets are also dated when they are + created, and this date is displayed with the name when you are listing + or selecting a FileSet. For more on backup levels see below. + + See also {\bf Ignore FileSet Changes} in the + \ilink{FileSet Resource definition}{FileSetResource} in the Director + chapter of this document. + +\label{filenamelengths} +\section{Do you really handle unlimited path lengths?} +\item [How Can You Claim to Handle Unlimited Path and Filename Lengths + when All Other Programs Have Fixed Limits?] +\index[general]{Path and Filename Lengths} + Most of those other programs have been around for a long time, in fact + since the beginning of Unix, which means that they were designed for + rather small fixed length path and filename lengths. Over the years, + these restrictions have been relaxed allowing longer names. Bacula on + the other hand was designed in 2000, and so from the start, Path and + Filenames have been kept in buffers that start at 256 bytes in length, + but can grow as needed to handle any length. Most of the work is + carried out by lower level routines making the coding rather easy. + + Note that due to limitations Win32 path and filenames cannot exceed + 260 characters. By using Win32 Unicode functions, we will remove this + restriction in later versions of Bacula. + +\label{unique} +\section{What Is the Really Unique Feature of Bacula?} +\item [What Is the Really Unique Feature of Bacula?] +\index[general]{Unique Feature of Bacula} + Well, it is hard to come up with unique features when backup programs + for Unix machines have been around since the 1960s. That said, I + believe that Bacula is the first and only program to use a standard SQL + interface to catalog its database. Although this adds a bit of + complexity and possibly overhead, it provides an amazingly rich set of + features that are easy to program and enhance. The current code has + barely scratched the surface in this regard (version 1.38). + + The second feature, which gives a lot of power and flexibility to Bacula + is the Bootstrap record definition. + + The third unique feature, which is currently (1.30) unimplemented, and + thus can be called vaporware :-), is Base level saves. When + implemented, this will enormously reduce tape usage. + +\label{sequence} +\section{How can I force one job to run after another?} +\item [If I Run Multiple Simultaneous Jobs, How Can I Force One + Particular Job to Run After Another Job? ] +\index[general]{Multiple Simultaneous Jobs} +Yes, you can set Priorities on your jobs so that they run in the order you +specify. Please see: +\ilink{the Priority record}{Priority} in the Job resource. + +\label{nomail} +\section{I Am Not Getting Email Notification, What Can I Do? } +\item [I Am Not Getting Email Notification, What Can I Do? ] +\index[general]{No Email Notification} + The most common problem is that you have not specified a fully qualified + email address and your bsmtp server is rejecting the mail. The next + most common problem is that your bsmtp server doesn't like the syntax on + the From part of the message. For more details on this and other + problems, please see the \ilink{ Getting Email Notification to + Work}{email} section of the Tips chapter of this manual. The section + \ilink{ Getting Notified of Job Completion}{notification} of the Tips + chapter may also be useful. For more information on the {\bf bsmtp} + mail program, please see \ilink{bsmtp in the Volume Utility Tools + chapter}{bsmtp} of this manual. + +\label{periods} +\section{My retention periods don't work} +\item [I Change Recycling, Retention Periods, or File Sizes in my Pool + Resource and they Still Don't Work.] +\index[general]{Recycling} +\index[general]{Retention Periods} +\index[general]{Pool changes} + The different variables associated with a Pool are defined in the Pool + Resource, but are actually read by Bacula from the Catalog database. On + Bacula versions prior to 1.30, after changing your Pool Resource, you must + manually update the corresponding values in the Catalog by using the {\bf + update pool} command in the Console program. In Bacula version 1.30, Bacula + does this for you automatically every time it starts. + + When Bacula creates a Media record (Volume), it uses many default values from + the Pool record. If you subsequently change the Pool record, the new values + will be used as a default for the next Volume that is created, but if you + want the new values to apply to existing Volumes, you must manually update + the Volume Catalog entry using the {\bf update volume} command in the Console + program. + +\label{CompressionNotWorking} +\section{Why aren't my files compressed?} +\item [I Have Configured Compression On, But None of My Files Are + Compressed. Why?] +\index[general]{Compression} + There are two kinds of compression. One is tape compression. This is done by + the tape drive hardware, and you either enable or disable it with system + tools such as {\bf mt}. This compression works independently of Bacula, + and when it is enabled, you should not use the Bacula software + compression. + + Bacula also has software compression code in the File daemons, which you + normally need to enable only when backing up to file Volumes. There are + two conditions necessary to enable the Bacula software compression. + +\begin{enumerate} +\item You must have the zip development libraries loaded on your system + when building Bacula and Bacula must find this library, normally {\bf + /usr/lib/libz.a}. On Red Hat systems, this library is provided by the + {\bf zlib-devel} rpm. + + If the library is found by Bacula during the {\bf ./configure} it will + be mentioned in the {\bf config.out} line by: + +\footnotesize +\begin{verbatim} + ZLIB support: yes + +\end{verbatim} +\normalsize + +\item You must add the {\bf compression=gzip} option on your Include + statement in the Director's configuration file. +\end{enumerate} + +\label{NewTape} +\item [Bacula is Asking for a New Tape After 2 GB of Data but My Tape + holds 33 GB. Why?] +\index[general]{Tape capacity} +There are several reasons why Bacula will request a new tape. + +\begin{itemize} +\item There is an I/O error on the tape. Bacula prints an error message and + requests a new tape. Bacula does not attempt to continue writing after an + I/O error. +\item Bacula encounters and end of medium on the tape. This is not always + distinguishable from an I/O error. +\item You have specifically set some size limitation on the tape. For example + the {\bf Maximum Volume Bytes} or {\bf Maximum Volume Files} in the + Director's Pool resource, or {\bf Maximum Volume Size} in the Storage + daemon's Device resource. +\end{itemize} + +\label{LevelChanging} +\section{Incremental backups are not working} +\item [Bacula is Not Doing the Right Thing When I Request an Incremental + Backup. Why?] +\index[general]{Incremental backups} + As explained in one of the previous questions, Bacula will automatically + upgrade an Incremental or Differential job to a Full backup if it cannot + find a prior Full backup or a suitable Full backup. For the gory + details on how/when Bacula decides to upgrade levels please see the + \ilink{Level record}{Level} in the Director's configuration chapter of + this manual. + + If after reading the above mentioned section, you believe that Bacula is not + correctly handling the level (Differential/Incremental), please send us the + following information for analysis: + +\begin{itemize} +\item Your Director's configuration file. +\item The output from {\bf list jobs} covering the period where you are + having the problem. +\item The Job report output from the prior Full save (not critical). +\item An {\bf llist jobid=nnn} where nnn is the JobId of the prior Full save. + +\item The Job report output from the save that is doing the wrong thing (not + critical). +\item An {\bf llist jobid=nnn} where nnn is the JobId of the job that was not + correct. +\item An explanation of what job went wrong and why you think it did. + \end{itemize} + +The above information can allow us to analyze what happened, without it, +there is not much we can do. + +\label{WaitForever} +\section{I am waiting forever for a backup of an offsite machine} +\item [I am Backing Up an Offsite Machine with an Unreliable Connection. + The Director Waits Forever for the Client to Contact the SD. What Can I + Do?] +\index[general]{Backing Up Offsite Machines} + Bacula was written on the assumption that it will have a good TCP/IP + connection between all the daemons. As a consequence, the current + Bacula doesn't deal with faulty connections very well. This situation + is slowly being corrected over time. + + There are several things you can do to improve the situation. + +\begin{itemize} +\item Upgrade to version 1.32 and use the new SDConnectTimeout record. For + example, set: + +\footnotesize +\begin{verbatim} + SD Connect Timeout = 5 min + +\end{verbatim} +\normalsize + +in the FileDaemon resource. +\item Run these kinds of jobs after all other jobs. + \end{itemize} + +\label{sshHanging} +\section{SSH hangs forever after starting Bacula} +\item [When I ssh into a machine and start Bacula then attempt to exit, + ssh hangs forever.] +\index[general]{ssh hangs} + This happens because Bacula leaves stdin, stdout, and stderr open for + debug purposes. To avoid it, the simplest thing to do is to redirect + the output of those files to {\bf /dev/null} or another file in your + startup script (the Red Hat autostart scripts do this automatically). + For example, you start the Director with: + +\footnotesize +\begin{verbatim} + bacula-dir -c bacula-dir.conf ... 0>\&1 2>\&1 >/dev/null + +\end{verbatim} +\normalsize + +and likewise for the other daemons. + +\label{RetentionPeriods} +\section{I'm confused by retention periods} +\item [I'm confused by the different Retention periods: File Retention, + Job Retention, Volume Retention. Why are there so many?] +\index[general]{Retention Periods} + Yes, this certainly can be confusing. The basic reason for so many is + to allow flexibility. The File records take quite a lot of space in the + catalog, so they are typically records you want to remove rather + quickly. The Job records, take very little space, and they can be + useful even without the File records to see what Jobs actually ran and + when. One must understand that if the File records are removed from the + catalog, you cannot use the {\bf restore} command to restore an + individual file since Bacula no longer knows where it is. However, as + long as the Volume Retention period has not expired, the data will still + be on the tape, and can be recovered from the tape. + + For example, I keep a 30 day retention period for my Files to keep my + catalog from getting too big, but I keep my tapes for a minimum of one + year, just in case. + +\label{MaxVolumeSize} +\section{MaxVolumeSize is ignored} +\item [Why Does Bacula Ignore the MaxVolumeSize Set in my Pool?] +\index[general]{MaxVolumeSize} + The MaxVolumeSize that Bacula uses comes from the Media record, so most + likely you changed your Pool, which is used as the default for creating + Media records, {\bf after} you created your Volume. Check what is in + the Media record by doing: + +\footnotesize +\begin{verbatim} +llist Volume=xxx +\end{verbatim} +\normalsize + +If it doesn't have the right value, you can use: + +\footnotesize +\begin{verbatim} +update Volume=xxx +\end{verbatim} +\normalsize + +to change it. + +\label{ConnectionRefused} +\section{I get a Connection refused when connecting to my Client} +\item [In connecting to my Client, I get "ERR:Connection Refused. Packet + Size too big from File daemon:192.168.1.4:9102" Why?] +\index[general]{ERR:Connection Refused} + This is typically a communications error resulting from one of the + following: + + +\begin{itemize} +\item Old versions of Bacula, usually a Win32 client, where two threads were + using the same I/O packet. Fixed in more recent versions. Please upgrade. +\item Some other program such as an HP Printer using the same port (9102 in + this case). +\end{itemize} + +If it is neither of the above, please submit a bug report at +\elink{bugs.bacula.org}{http://bugs.bacula.org}. + +Another solution might be to run the daemon with the debug option by: + +\footnotesize +\begin{verbatim} + Start a DOS shell Window. + cd c:\bacula\bin + bacula-fd -d100 -c c:\bacula\bin\bacula-fd.conf + +\end{verbatim} +\normalsize + +This will cause the FD to write a file {\bf bacula.trace} in the current +directory, which you can examine to determine the problem. + +\section{Long running jobs die with Pipe Error} +\item [During long running jobs my File daemon dies with Pipe Error, or + some other communications error. Why?] +\index[general]{Communications Errors} +\index[general]{Pipe Errors} +\index[general]{slow} +\index[general]{Backups!slow} + There are a number of reasons why a connection might break. + Most often, it is a router between your two computers that times out + inactive lines (not respecting the keepalive feature that Bacula uses). + In that case, you can use the {\bf Heartbeat Interval} directive in + both the Storage daemon and the File daemon. + + In at least one case, the problem has been a bad driver for a Win32 + NVidia NForce 3 ethernet card with driver (4.4.2 17/05/2004). + In this case, a good driver is (4.8.2.0 06/04/2005). Moral of + the story, make sure you have the latest ethernet drivers + loaded, or use the following workaround as suggested by Thomas + Simmons for Win32 machines: + + Browse to: + Start \gt{} Control Panel \gt{} Network Connections + + Right click the connection for the nvidia adapter and select properties. + Under the General tab, click "Configure...". Under the Advanced tab set + "Checksum Offload" to disabled and click OK to save the change. + + Lack of communications, or communications that get interrupted can + also be caused by Linux firewalls where you have a rule that throttles + connections or traffic. For example, if you have: + +\footnotesize +\begin{verbatim} +iptables -t filter -A INPUT -m limit --limit 3/second --limit-burst 3 -j DROP +\end{verbatim} +\normalsize + + you will want to add the following rules {\bf before} the above rule: +\footnotesize +\begin{verbatim} +iptables -t filter -A INPUT --dport 9101 -j ACCEPT +iptables -t filter -A INPUT --dport 9102 -j ACCEPT +iptables -t filter -A INPUT --dport 9103 -j ACCEPT +\end{verbatim} +\normalsize + This will ensure that any Bacula traffic will not get terminated because + of high usage rates. + +\section{How do I tell the Job which Volume to use?} +\item[I can't figure out how to tell the job which volume to use] + \index[general]{What tape to mount} + This is an interesting statement. I now see that a number of people new to + Bacula have the same problem as you, probably from using programs like tar. + + In fact, you do not tell Bacula what tapes to use. It is the inverse. Bacula + tells you want tapes it wants. You put tapes at its disposition and it + chooses. + + Now, if you *really* want to be tricky and try to tell Bacula what to do, it + will be reasonable if for example you mount a valid tape that it can use on a + drive, it will most likely go ahead and use it. It also has a documented + algorithm for choosing tapes -- but you are asking for problems ... + + So, the trick is to invert your concept of things and put Bacula in charge of + handling the tapes. Once you do that, you will be fine. If you want to + anticipate what it is going to do, you can generally figure it out correctly + and get what you want. + + If you start with the idea that you are going to force or tell Bacula to use + particular tapes or you insist on trying to run in that kind of mode, you will + probably not be too happy. + + I don't want to worry about what tape has what data. That is what Bacula is + designed for. + + If you have an application where you *really* need to remove a tape each day + and insert a new one, it can be done the directives exist to accomplish that. + In such a case, one little "trick" to knowing what tape Bacula will want at + 2am while you are asleep is to run a tiny job at 4pm while you are still at + work that backs up say one directory, or even one file. You will quickly find + out what tape it wants, and you can mount it before you go home ... + +\label{Password generation} +\section{Password generation} +\item [How do I generate a password?] +\index[general]{MaxVolumeSize} + + Each daemon needs a password. This password occurs in the configuration + file for that daemon and in the bacula-dir.conf file. These passwords are + plain text. There is no special generation procedure. Most people just + use random text. + + Passwords are never sent over the wire in plain text. They are always + encrypted. + + Security surrounding these passwords is best left security to your + operating system. Passwords are not encrypted within Bacula + configuration files. + +\end{description} + \ No newline at end of file diff --git a/docs/manuals/fr/problems/fdl.tex b/docs/manuals/fr/problems/fdl.tex new file mode 100644 index 00000000..b46cd990 --- /dev/null +++ b/docs/manuals/fr/problems/fdl.tex @@ -0,0 +1,485 @@ +% TODO: maybe get rid of centering + +\chapter{GNU Free Documentation License} +\index[general]{GNU Free Documentation License} +\index[general]{License!GNU Free Documentation} + +\label{label_fdl} + + \begin{center} + + Version 1.2, November 2002 + + + Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc. + + \bigskip + + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + \bigskip + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +\end{center} + + +\begin{center} +{\bf\large Preamble} +\end{center} + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +\begin{center} +{\Large\bf 1. APPLICABILITY AND DEFINITIONS} +\end{center} + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The \textbf{"Document"}, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as \textbf{"you"}. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A \textbf{"Modified Version"} of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A \textbf{"Secondary Section"} is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The \textbf{"Cover Texts"} are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A \textbf{"Transparent"} copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called \textbf{"Opaque"}. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The \textbf{"Title Page"} means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as \textbf{"Acknowledgements"}, +\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.) +To \textbf{"Preserve the Title"} +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +\begin{center} +{\Large\bf 2. VERBATIM COPYING} +\end{center} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\begin{center} +{\Large\bf 3. COPYING IN QUANTITY} +\end{center} + + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\begin{center} +{\Large\bf 4. MODIFICATIONS} +\end{center} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} +\item[A.] + Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. + +\item[B.] + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + +\item[C.] + State on the Title page the name of the publisher of the + Modified Version, as the publisher. + +\item[D.] + Preserve all the copyright notices of the Document. + +\item[E.] + Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + +\item[F.] + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + +\item[G.] + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. + +\item[H.] + Include an unaltered copy of this License. + +\item[I.] + Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + +\item[J.] + Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + +\item[K.] + For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + +\item[L.] + Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. + +\item[M.] + Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + +\item[N.] + Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. + +\item[O.] + Preserve any Warranty Disclaimers. +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\begin{center} +{\Large\bf 5. COMBINING DOCUMENTS} +\end{center} + + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + +\begin{center} +{\Large\bf 6. COLLECTIONS OF DOCUMENTS} +\end{center} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +\begin{center} +{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS} +\end{center} + + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +\begin{center} +{\Large\bf 8. TRANSLATION} +\end{center} + + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +\begin{center} +{\Large\bf 9. TERMINATION} +\end{center} + + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\begin{center} +{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE} +\end{center} + + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +\begin{center} +{\Large\bf ADDENDUM: How to use this License for your documents} +% TODO: this is too long for table of contents +\end{center} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\bigskip +\begin{quote} + Copyright \copyright YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +\end{quote} +\bigskip + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + +\bigskip +\begin{quote} + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. +\end{quote} +\bigskip + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +%--------------------------------------------------------------------- diff --git a/docs/manuals/fr/problems/firewalls.tex b/docs/manuals/fr/problems/firewalls.tex new file mode 100644 index 00000000..1e93c04e --- /dev/null +++ b/docs/manuals/fr/problems/firewalls.tex @@ -0,0 +1,373 @@ +%% +%% + +\chapter{Dealing with Firewalls} +\label{FirewallsChapter} +\index[general]{Dealing with Firewalls } +\index[general]{Firewalls!Dealing with } + +If you have a firewall or a DMZ installed on your computer, you may experience +difficulties contacting one or more of the Clients to back them up. This is +especially true if you are trying to backup a Client across the Internet. + +\section{Technical Details} +\index[general]{Technical Details } +\index[general]{Details!Technical } + +If you are attempting to do this, the sequence of network events in Bacula to +do a backup are the following: + +\footnotesize +\begin{verbatim} +Console -> DIR:9101 +DIR -> SD:9103 +DIR -> FD:9102 +FD -> SD:9103 +\end{verbatim} +\normalsize + +Where hopefully it is obvious that DIR represents the Director, FD the File +daemon or client, and SD the Storage daemon. The numbers that follow those +names are the standard ports used by Bacula, and the -\gt{} represents the +left side making a connection to the right side (i.e. the right side is the +"server" or is listening on the specified port), and the left side is the +"client" that initiates the conversation. + +Note, port 9103 serves both the Director and the File daemon, each having its +own independent connection. + +If you are running {\bf iptables}, you might add something like: + +\footnotesize +\begin{verbatim} +-A FW-1-INPUT -m state --state NEW -m tcp -p tcp --dport 9101:9103 -j ACCEPT +\end{verbatim} +\normalsize + +on your server, and + +\footnotesize +\begin{verbatim} +-A FW-1-INPUT -m state --state NEW -m tcp -p tcp --dport 9102 -j ACCEPT +\end{verbatim} +\normalsize + +on your client. In both cases, I assume that the machine is allowed to +initiate connections on any port. If not, you will need to allow outgoing +connections on ports 9102 and 9103 on your server and 9103 on your client. +Thanks to Raymond Norton for this tip. + +\section{A Concrete Example} +\index[general]{Example!Concrete } +\index[general]{Concrete Example } + +The following discussion was originally written by +Jesse Guardiani because he has 'internal' and 'external' requiring the +Director and the Client to use different IP addresses. His original +solution was to define two different Storage resources in the Director's +conf file each pointing to the same Storage daemon but with different +IP addresses. In Bacula 1.38.x this no longer works, because Bacula makes +a one-to-one association between a Storage daemon resource and a Device (such +as an Autochanger). As a consequence, I have modified his original +text to a method that I believe will work, but is as of yet untested +(KES - July 2006). + +My bacula server is on the 192.168.1.0/24 network at IP address 192.168.1.52. +For the sake of discussion we will refer to this network as the 'internal' +network because it connects to the internet through a NAT'd firewall. We will +call the network on the public (internet) side of the NAT'd firewall the +'external' network. Also, for the sake of discussion we will call my bacula +server: + +\footnotesize +\begin{verbatim} + server.int.mydomain.tld +\end{verbatim} +\normalsize + +when a fully qualified domain name is required, or simply: + +\footnotesize +\begin{verbatim} + server +\end{verbatim} +\normalsize + +if a hostname is adequate. We will call the various bacula daemons running on +the server.int.mydomain.tld machine: + +\footnotesize +\begin{verbatim} + server-fd + server-sd + server-dir +\end{verbatim} +\normalsize + +In addition, I have two clients that I want to back up with Bacula. The first +client is on the internal network. Its fully qualified domain name is: + +\footnotesize +\begin{verbatim} + private1.int.mydomain.tld +\end{verbatim} +\normalsize + +And its hostname is: + +\footnotesize +\begin{verbatim} + private1 +\end{verbatim} +\normalsize + +This machine is a client and therefore runs just one bacula daemon: + +\footnotesize +\begin{verbatim} + private1-fd +\end{verbatim} +\normalsize + +The second client is on the external network. Its fully qualified domain name +is: + +\footnotesize +\begin{verbatim} + public1.mydomain.tld +\end{verbatim} +\normalsize + +And its hostname is: + +\footnotesize +\begin{verbatim} + public1 +\end{verbatim} +\normalsize + +This machine also runs just one bacula daemon: + +\footnotesize +\begin{verbatim} + public1-fd +\end{verbatim} +\normalsize + +Finally, I have a NAT firewall/gateway with two network interfaces. The first +interface is on the internal network and serves as a gateway to the internet +for all the machines attached to the internal network (For example, +server.int.mydomain.tld and private1.int.mydomain.tld). The second interface +is on the external (internet) network. The external interface has been +assigned the name: + +\footnotesize +\begin{verbatim} + firewall.mydomain.tld +\end{verbatim} +\normalsize + +Remember: + +\footnotesize +\begin{verbatim} + *.int.mydomain.tld = internal network + *.mydomain.tld = external network +\end{verbatim} +\normalsize + +\subsection{The Bacula Configuration Files for the Above} +\index[general]{Above!Bacula Configuration Files for the } +\index[general]{Bacula Configuration Files for the Above } + +server-sd manages a 4 tape AIT autoloader. All of my backups are written to +server-sd. I have just *one* Device resource in my server-sd.conf file: + +\footnotesize +\begin{verbatim} +Autochanger { + Name = "autochanger1";\ + Device = Drive0 + Changer Device = /dev/ch0; + Changer Command = "/usr/local/sbin/chio-bacula %c %o %S %a"; +} +Device { + Name = Drive0 + DriveIndex = 0 + Media Type = AIT-1; + Archive Device = /dev/nrsa1; + Label Media = yes; + AutoChanger = yes; + AutomaticMount = yes; # when device opened, read it + AlwaysOpen = yes; + Hardware End of Medium = No + Fast Forward Space File = No + BSF at EOM = yes +} +\end{verbatim} +\normalsize + +(note, please see +\ilink{the Tape Testing}{FreeBSDTapes} chapter of this manual +for important FreeBSD information.) However, unlike previously, there +is only one Storage definition in my server-dir.conf file: + +\footnotesize +\begin{verbatim} +Storage { + Name = "autochanger1" # Storage device for backing up + Address = Storage-server + SDPort = 9103 + Password = "mysecretpassword" + Device = "autochanger1" + Media Type = AIT-1 + Autochanger = yes +} +\end{verbatim} +\normalsize + +Note that the Storage resource uses neither of the two addresses to +the Storage daemon -- neither server.int.mydomain.tld nor +firewall.mydomain.tld, but instead uses the address Storage-server. + +What is key is that in the internal net, Storage-server is resolved +to server.int.mydomain.tld, either with an entry in /etc/hosts, or by +creating and appropriate DNS entry, and on the external net (the Client +machine), Storage-server is resolved to firewall.mydomain.tld. + + +In addition to the above, I have two Client resources defined in +server-dir.conf: + +\footnotesize +\begin{verbatim} +Client { + Name = private1-fd + Address = private1.int.mydomain.tld + FDPort = 9102 + Catalog = MyCatalog + Password = "mysecretpassword" # password for FileDaemon +} +Client { + Name = public1-fd + Address = public1.mydomain.tld + FDPort = 9102 + Catalog = MyCatalog + Password = "mysecretpassword" # password for FileDaemon +} +\end{verbatim} +\normalsize + +And finally, to tie it all together, I have two Job resources defined in +server-dir.conf: + +\footnotesize +\begin{verbatim} +Job { + Name = "Private1-Backup" + Type = Backup + Client = private1-fd + FileSet = "Private1" + Schedule = "WeeklyCycle" + Storage = "autochanger1-int" + Messages = Standard + Pool = "Weekly" + Write Bootstrap = "/var/db/bacula/Private1-Backup.bsr" + Priority = 12 +} +Job { + Name = "Public1-Backup" + Type = Backup + Client = public1-fd + FileSet = "Public1" + Schedule = "WeeklyCycle" + Storage = "autochanger1-ext" + Messages = Standard + Pool = "Weekly" + Write Bootstrap = "/var/db/bacula/Public1-Backup.bsr" + Priority = 13 +} +\end{verbatim} +\normalsize + +It is important to notice that because the 'Private1-Backup' Job is intended +to back up a machine on the internal network so it resolves Storage-server +to contact the Storage daemon via the internal net. +On the other hand, the 'Public1-Backup' Job is intended to +back up a machine on the external network, so it resolves Storage-server +to contact the Storage daemon via the external net. + +I have left the Pool, Catalog, Messages, FileSet, Schedule, and Director +resources out of the above server-dir.conf examples because they are not +pertinent to the discussion. + +\subsection{How Does It Work?} +\index[general]{How Does It Work? } +\index[general]{Work!How Does It } + +If I want to run a backup of private1.int.mydomain.tld and store that backup +using server-sd then my understanding of the order of events is this: + +\begin{enumerate} +\item I execute my Bacula 'console' command on server.int.mydomain.tld. +\item console connects to server-dir. +\item I tell console to 'run' backup Job 'Private1-Backup'. +\item console relays this command to server-dir. +\item server-dir connects to private1-fd at private1.int.mydomain.tld:9102 +\item server-dir tells private1-fd to start sending the files defined in the + 'Private1-Backup' Job's FileSet resource to the Storage resource + 'autochanger1', which we have defined in server-dir.conf as having the +address:port of Storage-server, which is mapped by DNS to server.int.mydomain.tld. +\item private1-fd connects to server.int.mydomain.tld:9103 and begins sending + files. + \end{enumerate} + +Alternatively, if I want to run a backup of public1.mydomain.tld and store +that backup using server-sd then my understanding of the order of events is +this: + +\begin{enumerate} +\item I execute my Bacula 'console' command on server.int.mydomain.tld. +\item console connects to server-dir. +\item I tell console to 'run' backup Job 'Public1-Backup'. +\item console relays this command to server-dir. +\item server-dir connects, through the NAT'd firewall, to public1-fd at + public1.mydomain.tld:9102 +\item server-dir tells public1-fd to start sending the files defined in the + 'Public1-Backup' Job's FileSet resource to the Storage resource + 'autochanger1', which we have defined in server-dir.conf as having the + same address:port as above of Storage-server, but which on this machine + is resolved to firewall.mydomain.tld:9103. +\item public1-fd connects to firewall.mydomain.tld:9103 and begins sending + files. + \end{enumerate} + +\subsection{Important Note} +\index[general]{Important Note } +\index[general]{Note!Important } + +In order for the above 'Public1-Backup' Job to succeed, +firewall.mydomain.tld:9103 MUST be forwarded using the firewall's +configuration software to server.int.mydomain.tld:9103. Some firewalls call +this 'Server Publication'. Others may call it 'Port Forwarding'. + +\subsection{Firewall Problems} +\index[general]{Firewall Problems} +\index[general]{Problems!Firewalls} +Either a firewall or a router may decide to timeout and terminate +open connections if they are not active for a short time. By Internet +standards the period should be two hours, and should be indefinitely +extended if KEEPALIVE is set as is the case by Bacula. If your firewall +or router does not respect these rules, you may find Bacula connections +terminated. In that case, the first thing to try is turning on the +{\bf Heart Beat Interval} both in the File daemon and the Storage daemon +and set an interval of say five minutes. + +Also, if you have denial of service rate limiting in your firewall, this +too can cause Bacula disconnects since Bacula can at times use very high +access rates. To avoid this, you should implement default accept +rules for the Bacula ports involved before the rate limiting rules. + +Finally, if you have a Windows machine, it will most likely by default +disallow connections to the Bacula Windows File daemon. See the +Windows chapter of this manual for additional details. diff --git a/docs/manuals/fr/problems/fix_tex.pl b/docs/manuals/fr/problems/fix_tex.pl new file mode 100755 index 00000000..98657576 --- /dev/null +++ b/docs/manuals/fr/problems/fix_tex.pl @@ -0,0 +1,184 @@ +#!/usr/bin/perl -w +# Fixes various things within tex files. + +use strict; + +my %args; + + +sub get_includes { + # Get a list of include files from the top-level tex file. + my (@list,$file); + + foreach my $filename (@_) { + $filename or next; + # Start with the top-level latex file so it gets checked too. + push (@list,$filename); + + # Get a list of all the html files in the directory. + open IF,"<$filename" or die "Cannot open input file $filename"; + while () { + chomp; + push @list,"$1.tex" if (/\\include\{(.*?)\}/); + } + + close IF; + } + return @list; +} + +sub convert_files { + my (@files) = @_; + my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt); + + $cnt = 0; + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # We look for a line that starts with \item, and indent the two next lines (if not blank) + # by three spaces. + my $linecnt = 3; + $indentcnt = 0; + $output = ""; + # Process a line at a time. + foreach (split(/\n/,$filedata)) { + $_ .= "\n"; # Put back the return. + # If this line is less than the third line past the \item command, + # and the line isn't blank and doesn't start with whitespace + # add three spaces to the start of the line. Keep track of the number + # of lines changed. + if ($linecnt < 3 and !/^\\item/) { + if (/^[^\n\s]/) { + $output .= " " . $_; + $indentcnt++; + } else { + $output .= $_; + } + $linecnt++; + } else { + $linecnt = 3; + $output .= $_; + } + /^\\item / and $linecnt = 1; + } + + + # This is an item line. We need to process it too. If inside a \begin{description} environment, convert + # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'. + $itemcnt = 0; + $filedata = $output; + $output = ""; + my ($before,$descrip,$this,$between); + + # Find any \begin{description} environment + while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) { + $output .= $` . $1; + $filedata = $3 . $'; + $descrip = $2; + + # Search for \item {\bf xxx} + while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) { + $descrip = $'; + $output .= $`; + ($between,$descrip) = find_matching_brace($descrip); + if (!$descrip) { + $linecnt = $output =~ tr/\n/\n/; + print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip); + } + + # Now do the replacement. + $between = '{' . $between . '}' if ($between =~ /\[|\]/); + $output .= "\\item \[$between\]"; + $itemcnt++; + } + $output .= $descrip; + } + $output .= $filedata; + + # If any hyphens or \item commnads were converted, save the file. + if ($indentcnt or $itemcnt) { + open OF,">$file" or die "Cannot open output file $file"; + print OF $output; + close OF; + print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n"; + print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n"; + } + + $cnt += $indentcnt + $itemcnt; + } + return $cnt; +} + +sub find_matching_brace { + # Finds text up to the next matching brace. Assumes that the input text doesn't contain + # the opening brace, but we want to find text up to a matching closing one. + # Returns the text between the matching braces, followed by the rest of the text following + # (which does not include the matching brace). + # + my $str = shift; + my ($this,$temp); + my $cnt = 1; + + while ($cnt) { + # Ignore verbatim constructs involving curly braces, or if the character preceding + # the curly brace is a backslash. + if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) { + $this .= $`; + $str = $'; + $temp = $&; + + if ((substr($this,-1,1) eq '\\') or + $temp =~ /^\\verb/) { + $this .= $temp; + next; + } + + $cnt += ($temp eq '{') ? 1 : -1; + # If this isn't the matching curly brace ($cnt > 0), include the brace. + $this .= $temp if ($cnt); + } else { + # No matching curly brace found. + return ($this . $str,''); + } + } + return ($this,$str); +} + +sub check_arguments { + # Checks command-line arguments for ones starting with -- puts them into + # a hash called %args and removes them from @ARGV. + my $args = shift; + my $i; + + for ($i = 0; $i < $#ARGV; $i++) { + $ARGV[$i] =~ /^\-+/ or next; + $ARGV[$i] =~ s/^\-+//; + $args{$ARGV[$i]} = ""; + delete ($ARGV[$i]); + + } +} + +################################################################## +# MAIN #### +################################################################## + +my @includes; +my $cnt; + +check_arguments(\%args); +die "No Files given to Check\n" if ($#ARGV < 0); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +@includes = get_includes(@ARGV); + +$cnt = convert_files(@includes); +print "No lines changed\n" unless $cnt; diff --git a/docs/manuals/fr/problems/index.perl b/docs/manuals/fr/problems/index.perl new file mode 100644 index 00000000..bc4e1b60 --- /dev/null +++ b/docs/manuals/fr/problems/index.perl @@ -0,0 +1,564 @@ +# This module does multiple indices, supporting the style of the LaTex 'index' +# package. + +# Version Information: +# 16-Feb-2005 -- Original Creation. Karl E. Cunningham +# 14-Mar-2005 -- Clarified and Consolodated some of the code. +# Changed to smoothly handle single and multiple indices. + +# Two LaTeX index formats are supported... +# --- SINGLE INDEX --- +# \usepackage{makeidx} +# \makeindex +# \index{entry1} +# \index{entry2} +# \index{entry3} +# ... +# \printindex +# +# --- MULTIPLE INDICES --- +# +# \usepackage{makeidx} +# \usepackage{index} +# \makeindex -- latex2html doesn't care but LaTeX does. +# \newindex{ref1}{ext1}{ext2}{title1} +# \newindex{ref2}{ext1}{ext2}{title2} +# \newindex{ref3}{ext1}{ext2}{title3} +# \index[ref1]{entry1} +# \index[ref1]{entry2} +# \index[ref3]{entry3} +# \index[ref2]{entry4} +# \index{entry5} +# \index[ref3]{entry6} +# ... +# \printindex[ref1] +# \printindex[ref2] +# \printindex[ref3] +# \printindex +# ___________________ +# +# For the multiple-index style, each index is identified by the ref argument to \newindex, \index, +# and \printindex. A default index is allowed, which is indicated by omitting the optional +# argument. The default index does not require a \newindex command. As \index commands +# are encountered, their entries are stored according +# to the ref argument. When the \printindex command is encountered, the stored index +# entries for that argument are retrieved and printed. The title for each index is taken +# from the last argument in the \newindex command. +# While processing \index and \printindex commands, if no argument is given the index entries +# are built into a default index. The title of the default index is simply "Index". +# This makes the difference between single- and multiple-index processing trivial. +# +# Another method can be used by omitting the \printindex command and just using \include to +# pull in index files created by the makeindex program. These files will start with +# \begin{theindex}. This command is used to determine where to print the index. Using this +# approach, the indices will be output in the same order as the newindex commands were +# originally found (see below). Using a combination of \printindex and \include{indexfile} has not +# been tested and may produce undesireable results. +# +# The index data are stored in a hash for later sorting and output. As \printindex +# commands are handled, the order in which they were found in the tex filea is saved, +# associated with the ref argument to \printindex. +# +# We use the original %index hash to store the index data into. We append a \002 followed by the +# name of the index to isolate the entries in different indices from each other. This is necessary +# so that different indices can have entries with the same name. For the default index, the \002 is +# appended without the name. +# +# Since the index order in the output cannot be determined if the \include{indexfile} +# command is used, the order will be assumed from the order in which the \newindex +# commands were originally seen in the TeX files. This order is saved as well as the +# order determined from any printindex{ref} commands. If \printindex commnads are used +# to specify the index output, that order will be used. If the \include{idxfile} command +# is used, the order of the original newindex commands will be used. In this case the +# default index will be printed last since it doesn't have a corresponding \newindex +# command and its order cannot be determined. Mixing \printindex and \include{idxfile} +# commands in the same file is likely to produce less than satisfactory results. +# +# +# The hash containing index data is named %indices. It contains the following data: +#{ +# 'title' => { +# $ref1 => $indextitle , +# $ref2 => $indextitle , +# ... +# }, +# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +#} + + +# Globals to handle multiple indices. +my %indices; + +# This tells the system to use up to 7 words in index entries. +$WORDS_IN_INDEX = 10; + +# KEC 2-18-05 +# Handles the \newindex command. This is called if the \newindex command is +# encountered in the LaTex source. Gets the index ref and title from the arguments. +# Saves the index ref and title. +# Note that we are called once to handle multiple \newindex commands that are +# newline-separated. +sub do_cmd_newindex { + my $data = shift; + # The data is sent to us as fields delimited by their ID #'s. We extract the + # fields. + foreach my $line (split("\n",$data)) { + my @fields = split (/(?:\<\#\d+?\#\>)+/,$line); + + # The index name and title are the second and fourth fields in the data. + if ($line =~ /^ \001 + # @ -> \002 + # | -> \003 + $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines + # protect \001 occurring with images + $str =~ s/\001/\016/g; # 0x1 to 0xF + $str =~ s/\\\\/\011/g; # Double backslash -> 0xB + $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC + $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD + $str =~ s/!/\001/g; # Exclamation point -> 0x1 + $str =~ s/\013/!/g; # 0xD -> Exclaimation point + $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF + $str =~ s/@/\002/g; # At sign -> 0x2 + $str =~ s/\015/@/g; # 0xF to At sign + $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11 + $str =~ s/\|/\003/g; # Vertical line to 0x3 + $str =~ s/\017/|/g; # 0x11 to vertical line + $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is + $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot; + $str =~ s/\011/\\\\/g; # 0x11 to double backslash + local($key_part, $pageref) = split("\003", $str, 2); + + # For any keys of the form: blablabla!blablabla, which want to be split at the + # exclamation point, replace the ! with a comma and a space. We don't do it + # that way for this index. + $key_part =~ s/\001/, /g; + local(@keys) = split("\001", $key_part); + # If TITLE is not yet available use $before. + $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title))); + $TITLE = $before unless $TITLE; + # Save the reference + local($words) = ''; + if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; } + elsif ($SHORT_INDEX) { $words = &make_shortidxname; } + else { $words = &make_idxname; } + local($super_key) = ''; + local($sort_key, $printable_key, $cur_key); + foreach $key (@keys) { + $key =~ s/\016/\001/g; # revert protected \001s + ($sort_key, $printable_key) = split("\002", $key); + # + # RRM: 16 May 1996 + # any \label in the printable-key will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($printable_key =~ /tex2html_anchor_mark/ ) { + $printable_key =~ s/><\/A>$cross_ref_mark/ + $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_label = $external_labels{$label} unless + ($ref_label = $ref_files{$label}); + '"' . "$ref_label#$label" . '">' . + &get_ref_mark($label,$id)} + /geo; + } + $printable_key =~ s/<\#[^\#>]*\#>//go; + #RRM + # recognise \char combinations, for a \backslash + # + $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s + $printable_key =~ s/\&\#;\`
/\\/g; # ditto + $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto + # + # $sort_key .= "@$printable_key" if !($printable_key); # RRM + $sort_key .= "@$printable_key" if !($sort_key); # RRM + $sort_key =~ tr/A-Z/a-z/; + if ($super_key) { + $cur_key = $super_key . "\001" . $sort_key; + $sub_index{$super_key} .= $cur_key . "\004"; + } else { + $cur_key = $sort_key; + } + + # Append the $index_name to the current key with a \002 delimiter. This will + # allow the same index entry to appear in more than one index. + $index_key = $cur_key . "\002$index_name"; + + $index{$index_key} .= ""; + + # + # RRM, 15 June 1996 + # if there is no printable key, but one is known from + # a previous index-entry, then use it. + # + if (!($printable_key) && ($printable_key{$index_key})) + { $printable_key = $printable_key{$index_key}; } +# if (!($printable_key) && ($printable_key{$cur_key})) +# { $printable_key = $printable_key{$cur_key}; } + # + # do not overwrite the printable_key if it contains an anchor + # + if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ )) + { $printable_key{$index_key} = $printable_key || $key; } +# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ )) +# { $printable_key{$cur_key} = $printable_key || $key; } + + $super_key = $cur_key; + } + # + # RRM + # page-ranges, from |( and |) and |see + # + if ($pageref) { + if ($pageref eq "\(" ) { + $pageref = ''; + $next .= " from "; + } elsif ($pageref eq "\)" ) { + $pageref = ''; + local($next) = $index{$index_key}; +# local($next) = $index{$cur_key}; + # $next =~ s/[\|] *$//; + $next =~ s/(\n )?\| $//; + $index{$index_key} = "$next to "; +# $index{$cur_key} = "$next to "; + } + } + + if ($pageref) { + $pageref =~ s/\s*$//g; # remove trailing spaces + if (!$pageref) { $pageref = ' ' } + $pageref =~ s/see/see <\/i> /g; + # + # RRM: 27 Dec 1996 + # check if $pageref corresponds to a style command. + # If so, apply it to the $words. + # + local($tmp) = "do_cmd_$pageref"; + if (defined &$tmp) { + $words = &$tmp("<#0#>$words<#0#>"); + $words =~ s/<\#[^\#]*\#>//go; + $pageref = ''; + } + } + # + # RRM: 25 May 1996 + # any \label in the pageref section will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($pageref) { + if ($pageref =~ /tex2html_anchor_mark/ ) { + $pageref =~ s/><\/A>$cross_ref_mark/ + $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_files{$label} = ''; # ???? RRM + if ($index_labels{$label}) { $ref_label = ''; } + else { $ref_label = $external_labels{$label} + unless ($ref_label = $ref_files{$label}); + } + '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo; + } + $pageref =~ s/<\#[^\#>]*\#>//go; + + if ($pageref eq ' ') { $index{$index_key}='@'; } + else { $index{$index_key} .= $pageref . "\n | "; } + } else { + local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words); + $thisref =~ s/\n//g; + $index{$index_key} .= $thisref."\n | "; + } + #print "\nREF: $sort_key : $index_key :$index{$index_key}"; + + #join('',"$anchor_invisible_mark<\/A>",$_); + + "$anchor_invisible_mark<\/A>"; +} + + +# KEC. -- Copied from makeidx.perl, then modified to do multiple indices. +# Feeds the index entries to the output. This is called for each index to be built. +# +# Generates a list of lookup keys for index entries, from both %printable_keys +# and %index keys. +# Sorts the keys according to index-sorting rules. +# Removes keys with a 0x01 token. (duplicates?) +# Builds a string to go to the index file. +# Adds the index entries to the string if they belong in this index. +# Keeps track of which index is being worked on, so only the proper entries +# are included. +# Places the index just built in to the output at the proper place. +{ my $index_number = 0; +sub add_real_idx { + print "\nDoing the index ... Index Number $index_number\n"; + local($key, @keys, $next, $index, $old_key, $old_html); + my ($idx_ref,$keyref); + # RRM, 15.6.96: index constructed from %printable_key, not %index + @keys = keys %printable_key; + + while (/$idx_mark/) { + # Get the index reference from what follows the $idx_mark and + # remove it from the string. + s/$idxmark\002(.*?)\002/$idxmark/; + $idx_ref = $1; + $index = ''; + # include non- makeidx index-entries + foreach $key (keys %index) { + next if $printable_key{$key}; + $old_key = $key; + if ($key =~ s/###(.*)$//) { + next if $printable_key{$key}; + push (@keys, $key); + $printable_key{$key} = $key; + if ($index{$old_key} =~ /HREF="([^"]*)"/i) { + $old_html = $1; + $old_html =~ /$dd?([^#\Q$dd\E]*)#/; + $old_html = $1; + } else { $old_html = '' } + $index{$key} = $index{$old_key} . $old_html."\n | "; + }; + } + @keys = sort makeidx_keysort @keys; + @keys = grep(!/\001/, @keys); + my $cnt = 0; + foreach $key (@keys) { + my ($keyref) = $key =~ /.*\002(.*)/; + next unless ($idx_ref eq $keyref); # KEC. + $index .= &add_idx_key($key); + $cnt++; + } + print "$cnt Index Entries Added\n"; + $index = '
'.$index unless ($index =~ /^\s*/); + $index_number++; # KEC. + if ($SHORT_INDEX) { + print "(compact version with Legend)"; + local($num) = ( $index =~ s/\ 50 ) { + s/$idx_mark/$preindex
\n$index\n<\/DL>$preindex/o; + } else { + s/$idx_mark/$preindex
\n$index\n<\/DL>/o; + } + } else { + s/$idx_mark/
\n$index\n<\/DL>/o; } + } +} +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# The bibliography and the index should be treated as separate sections +# in their own HTML files. The \bibliography{} command acts as a sectioning command +# that has the desired effect. But when the bibliography is constructed +# manually using the thebibliography environment, or when using the +# theindex environment it is not possible to use the normal sectioning +# mechanism. This subroutine inserts a \bibliography{} or a dummy +# \textohtmlindex command just before the appropriate environments +# to force sectioning. +sub add_bbl_and_idx_dummy_commands { + local($id) = $global{'max_id'}; + + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg; + ## if ($bbl_cnt == 1) { + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo; + #} + $global{'max_id'} = $id; + # KEC. Modified to global substitution to place multiple index tokens. + s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go; + # KEC. Modified to pick up the optional argument to \printindex + s/[\\]printindex\s*(\[.*?\])?/ + do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego; + &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands); +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# For each textohtmlindex mark found, determine the index titles and headers. +# We place the index ref in the header so the proper index can be generated later. +# For the default index, the index ref is blank. +# +# One problem is that this routine is called twice.. Once for processing the +# command as originally seen, and once for processing the command when +# doing the name for the index file. We can detect that by looking at the +# id numbers (or ref) surrounding the \theindex command, and not incrementing +# index_number unless a new id (or ref) is seen. This has the side effect of +# having to unconventionally start the index_number at -1. But it works. +# +# Gets the title from the list of indices. +# If this is the first index, save the title in $first_idx_file. This is what's referenced +# in the navigation buttons. +# Increment the index_number for next time. +# If the indexname command is defined or a newcommand defined for indexname, do it. +# Save the index TITLE in the toc +# Save the first_idx_file into the idxfile. This goes into the nav buttons. +# Build index_labels if needed. +# Create the index headings and put them in the output stream. + +{ my $index_number = 0; # Will be incremented before use. + my $first_idx_file; # Static + my $no_increment = 0; + +sub do_cmd_textohtmlindex { + local($_) = @_; + my ($idxref,$idxnum,$index_name); + + # We get called from make_name with the first argument = "\001noincrement". This is a sign + # to not increment $index_number the next time we are called. We get called twice, once + # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name + # but doesn't use the result so we get called a second time by process_command. This works fine + # except for cases where there are multiple indices except if they aren't named, which is the case + # when the index is inserted by an include command in latex. In these cases we are only able to use + # the index number to decide which index to draw from, and we don't know how to increment that index + # number if we get called a variable number of times for the same index, as is the case between + # making html (one output file) and web (multiple output files) output formats. + if (/\001noincrement/) { + $no_increment = 1; + return; + } + + # Remove (but save) the index reference + s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e; + + # If we have an $idxref, the index name was specified. In this case, we have all the + # information we need to carry on. Otherwise, we need to get the idxref + # from the $index_number and set the name to "Index". + if ($idxref) { + $index_name = $indices{'title'}{$idxref}; + } else { + if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) { + $index_name = $indices{'title'}{$idxref}; + } else { + $idxref = ''; + $index_name = "Index"; + } + } + + $idx_title = "Index"; # The name displayed in the nav bar text. + + # Only set $idxfile if we are at the first index. This will point the + # navigation panel to the first index file rather than the last. + $first_idx_file = $CURRENT_FILE if ($index_number == 0); + $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar. + $toc_sec_title = $index_name; # Index link text in the toc. + $TITLE = $toc_sec_title; # Title for this index, from which its filename is built. + if (%index_labels) { &make_index_labels(); } + if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); } + else { $preindex = ''; } + local $idx_head = $section_headings{'textohtmlindex'}; + local($heading) = join('' + , &make_section_heading($TITLE, $idx_head) + , $idx_mark, "\002", $idxref, "\002" ); + local($pre,$post) = &minimize_open_tags($heading); + $index_number++ unless ($no_increment); + $no_increment = 0; + join('',"
\n" , $pre, $_); +} +} + +# Returns an index key, given the key passed as the first argument. +# Not modified for multiple indices. +sub add_idx_key { + local($key) = @_; + local($index, $next); + if (($index{$key} eq '@' )&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { $index .= "

\n
".&print_key."\n
"; } + else { $index .= "

\n
".&print_key."\n
"; } + } elsif (($index{$key})&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { + $next = "
".&print_key."\n : ". &print_idx_links; + } else { + $next = "
".&print_key."\n
". &print_idx_links; + } + $index .= $next."\n"; + $index_printed{$key} = 1; + } + + if ($sub_index{$key}) { + local($subkey, @subkeys, $subnext, $subindex); + @subkeys = sort(split("\004", $sub_index{$key})); + if ($SHORT_INDEX) { + $index .= "
".&print_key unless $index_printed{$key}; + $index .= "
\n"; + } else { + $index .= "
".&print_key."\n
" unless $index_printed{$key}; + $index .= "
\n"; + } + foreach $subkey (@subkeys) { + $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey}); + } + $index .= "
\n"; + } + return $index; +} + +1; # Must be present as the last line. diff --git a/docs/manuals/fr/problems/kaboom.tex b/docs/manuals/fr/problems/kaboom.tex new file mode 100644 index 00000000..a4e5bc57 --- /dev/null +++ b/docs/manuals/fr/problems/kaboom.tex @@ -0,0 +1,233 @@ +%% +%% + +\chapter{What To Do When Bacula Crashes (Kaboom)} +\label{KaboomChapter} +\index[general]{Kaboom!What To Do When Bacula Crashes } +\index[general]{What To Do When Bacula Crashes (Kaboom) } + +If you are running on a Linux system, and you have a set of working +configuration files, it is very unlikely that {\bf Bacula} will crash. As with +all software, however, it is inevitable that someday, it may crash, +particularly if you are running on another operating system or using a new or +unusual feature. + +This chapter explains what you should do if one of the three {\bf Bacula} +daemons (Director, File, Storage) crashes. When we speak of crashing, we +mean that the daemon terminates abnormally because of an error. There are +many cases where Bacula detects errors (such as PIPE errors) and will fail +a job. These are not considered crashes. In addition, under certain +conditions, Bacula will detect a fatal in the configuration, such as +lack of permission to read/write the working directory. In that case, +Bacula will force itself to crash with a SEGFAULT. However, before +crashing, Bacula will normally display a message indicating why. +For more details, please read on. + + +\section{Traceback} +\index[general]{Traceback} + +Each of the three Bacula daemons has a built-in exception handler which, in +case of an error, will attempt to produce a traceback. If successful the +traceback will be emailed to you. + +For this to work, you need to ensure that a few things are setup correctly on +your system: + +\begin{enumerate} +\item You must have a version of Bacula built with debug information turned + on and not stripped of debugging symbols. + +\item You must have an installed copy of {\bf gdb} (the GNU debugger), and it + must be on {\bf Bacula's} path. On some systems such as Solaris, {\bf + gdb} may be replaced by {\bf dbx}. + +\item The Bacula installed script file {\bf btraceback} must be in the same + directory as the daemon which dies, and it must be marked as executable. + +\item The script file {\bf btraceback.gdb} must have the correct path to it + specified in the {\bf btraceback} file. + +\item You must have a {\bf mail} program which is on {\bf Bacula's} path. + By default, this {\bf mail} program is set to {\bf bsmtp}, so it must + be correctly configured. + +\item If you run either the Director or Storage daemon under a non-root + userid, you will most likely need to modify the {\bf btraceback} file + to do something like {\bf sudo} (raise to root priority) for the + call to {\bf gdb} so that it has the proper permissions to debug + Bacula. +\end{enumerate} + +If all the above conditions are met, the daemon that crashes will produce a +traceback report and email it to you. If the above conditions are not true, +you can either run the debugger by hand as described below, or you may be able +to correct the problems by editing the {\bf btraceback} file. I recommend not +spending too much time on trying to get the traceback to work as it can be +very difficult. + +The changes that might be needed are to add a correct path to the {\bf gdb} +program, correct the path to the {\bf btraceback.gdb} file, change the {\bf +mail} program or its path, or change your email address. The key line in the +{\bf btraceback} file is: + +\footnotesize +\begin{verbatim} +gdb -quiet -batch -x /home/kern/bacula/bin/btraceback.gdb \ + $1 $2 2>\&1 | bsmtp -s "Bacula traceback" your-address@xxx.com +\end{verbatim} +\normalsize + +Since each daemon has the same traceback code, a single btraceback file is +sufficient if you are running more than one daemon on a machine. + +\section{Testing The Traceback} +\index[general]{Traceback!Testing The } +\index[general]{Testing The Traceback } + +To "manually" test the traceback feature, you simply start {\bf Bacula} then +obtain the {\bf PID} of the main daemon thread (there are multiple threads). +The output produced here will look different depending on what OS and what +version of the kernel you are running. +Unfortunately, the output had to be split to fit on this page: + +\footnotesize +\begin{verbatim} +[kern@rufus kern]$ ps fax --columns 132 | grep bacula-dir + 2103 ? S 0:00 /home/kern/bacula/k/src/dird/bacula-dir -c + /home/kern/bacula/k/src/dird/dird.conf + 2104 ? S 0:00 \_ /home/kern/bacula/k/src/dird/bacula-dir -c + /home/kern/bacula/k/src/dird/dird.conf + 2106 ? S 0:00 \_ /home/kern/bacula/k/src/dird/bacula-dir -c + /home/kern/bacula/k/src/dird/dird.conf + 2105 ? S 0:00 \_ /home/kern/bacula/k/src/dird/bacula-dir -c + /home/kern/bacula/k/src/dird/dird.conf +\end{verbatim} +\normalsize + +which in this case is 2103. Then while Bacula is running, you call the program +giving it the path to the Bacula executable and the {\bf PID}. In this case, +it is: + +\footnotesize +\begin{verbatim} +./btraceback /home/kern/bacula/k/src/dird 2103 +\end{verbatim} +\normalsize + +It should produce an email showing you the current state of the daemon (in +this case the Director), and then exit leaving {\bf Bacula} running as if +nothing happened. If this is not the case, you will need to correct the +problem by modifying the {\bf btraceback} script. + +Typical problems might be that {\bf gdb} or {\bf dbx} for Solaris is not on +the default path. Fix this by specifying the full path to it in the {\bf +btraceback} file. Another common problem is that you haven't modified the +script so that the {\bf bsmtp} program has an appropriate smtp server or +the proper syntax for your smtp server. If you use the {\bf mail} program +and it is not on the default path, it will also fail. On some systems, it +is preferable to use {\bf Mail} rather than {\bf mail}. + +\section{Getting A Traceback On Other Systems} +\index[general]{Getting A Traceback On Other Systems} +\index[general]{Systems!Getting A Traceback On Other} + +It should be possible to produce a similar traceback on systems other than +Linux, either using {\bf gdb} or some other debugger. Solaris with {\bf dbx} +loaded works quite fine. On other systems, you will need to modify the {\bf +btraceback} program to invoke the correct debugger, and possibly correct the +{\bf btraceback.gdb} script to have appropriate commands for your debugger. If +anyone succeeds in making this work with another debugger, please send us a +copy of what you modified. Please keep in mind that for any debugger to +work, it will most likely need to run as root, so you may need to modify +the {\bf btraceback} script accordingly. + +\label{ManuallyDebugging} +\section{Manually Running Bacula Under The Debugger} +\index[general]{Manually Running Bacula Under The Debugger} +\index[general]{Debugger!Manually Running Bacula Under The} + +If for some reason you cannot get the automatic traceback, or if you want to +interactively examine the variable contents after a crash, you can run Bacula +under the debugger. Assuming you want to run the Storage daemon under the +debugger (the technique is the same for the other daemons, only the name +changes), you would do the following: + +\begin{enumerate} +\item Start the Director and the File daemon. If the Storage daemon also + starts, you will need to find its PID as shown above (ps fax | grep + bacula-sd) and kill it with a command like the following: + +\footnotesize +\begin{verbatim} + kill -15 PID +\end{verbatim} +\normalsize + +where you replace {\bf PID} by the actual value. + +\item At this point, the Director and the File daemon should be running but + the Storage daemon should not. + +\item cd to the directory containing the Storage daemon + +\item Start the Storage daemon under the debugger: + + \footnotesize +\begin{verbatim} + gdb ./bacula-sd +\end{verbatim} +\normalsize + +\item Run the Storage daemon: + + \footnotesize +\begin{verbatim} + run -s -f -c ./bacula-sd.conf +\end{verbatim} +\normalsize + +You may replace the {\bf ./bacula-sd.conf} with the full path to the Storage +daemon's configuration file. + +\item At this point, Bacula will be fully operational. + +\item In another shell command window, start the Console program and do what + is necessary to cause Bacula to die. + +\item When Bacula crashes, the {\bf gdb} shell window will become active and + {\bf gdb} will show you the error that occurred. + +\item To get a general traceback of all threads, issue the following command: + + +\footnotesize +\begin{verbatim} + thread apply all bt +\end{verbatim} +\normalsize + +After that you can issue any debugging command. +\end{enumerate} + +\section{Getting Debug Output from Bacula} +\index[general]{Getting Debug Output from Bacula } +Each of the daemons normally has debug compiled into the program, but +disabled. There are two ways to enable the debug output. One is to add the +{\bf -d nnn} option on the command line when starting the debugger. The {\bf +nnn} is the debug level, and generally anything between 50 and 200 is +reasonable. The higher the number, the more output is produced. The output is +written to standard output. + +The second way of getting debug output is to dynamically turn it on using the +Console using the {\bf setdebug} command. The full syntax of the command is: + +\footnotesize +\begin{verbatim} + setdebug level=nnn client=client-name storage=storage-name dir +\end{verbatim} +\normalsize + +If none of the options are given, the command will prompt you. You can +selectively turn on/off debugging in any or all the daemons (i.e. it is not +necessary to specify all the components of the above command). diff --git a/docs/manuals/fr/problems/latex2html-init.pl b/docs/manuals/fr/problems/latex2html-init.pl new file mode 100644 index 00000000..14b5c319 --- /dev/null +++ b/docs/manuals/fr/problems/latex2html-init.pl @@ -0,0 +1,10 @@ +# This file serves as a place to put initialization code and constants to +# affect the behavior of latex2html for generating the bacula manuals. + +# $LINKPOINT specifies what filename to use to link to when creating +# index.html. Not that this is a hard link. +$LINKPOINT='"$OVERALL_TITLE"'; + + +# The following must be the last line of this file. +1; diff --git a/docs/manuals/fr/problems/problems.tex b/docs/manuals/fr/problems/problems.tex new file mode 100644 index 00000000..b6a1d5ba --- /dev/null +++ b/docs/manuals/fr/problems/problems.tex @@ -0,0 +1,81 @@ +%% +%% +%% The following characters must be preceded by a backslash +%% to be entered as printable characters: +%% +%% # $ % & ~ _ ^ \ { } +%% + +\documentclass[11pt,a4paper]{book} +\usepackage{html} +\usepackage{float} +\usepackage{graphicx} +\usepackage{bacula} +\usepackage{longtable} +\usepackage{makeidx} +\usepackage{index} +\usepackage{setspace} +\usepackage{hyperref} +\usepackage{url} + + +\makeindex +\newindex{general}{idx}{ind}{General Index} + +\sloppy + +\begin{document} +\sloppy + +\newfont{\bighead}{cmr17 at 36pt} +\parskip 10pt +\parindent 0pt + +\title{\includegraphics{./bacula-logo.eps} \\ \bigskip + \Huge{Bacula Problem Resolution Guide} + \begin{center} + \large{It comes in the night and sucks + the essence from your computers. } + \end{center} +} + + +\author{Kern Sibbald} +\date{\vspace{1.0in}\today \\ + This manual documents Bacula version \input{version} \\ + \vspace{0.2in} + Copyright \copyright 1999-2007, Free Software Foundation Europe + e.V. \\ + \vspace{0.2in} + Permission is granted to copy, distribute and/or modify this document under the terms of the + GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU Free Documentation License". +} + +\maketitle + +\clearpage +\tableofcontents +\clearpage +\listoffigures +\clearpage +\listoftables +\clearpage + +\include{faq} +\include{tips} +\include{tapetesting} +\include{firewalls} +\include{kaboom} +\include{fdl} + + +% The following line tells link_resolver.pl to not include these files: +% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main + +% pull in the index +\clearpage +\printindex[general] + +\end{document} diff --git a/docs/manuals/fr/problems/rpm-faq.tex b/docs/manuals/fr/problems/rpm-faq.tex new file mode 100644 index 00000000..1e37cc59 --- /dev/null +++ b/docs/manuals/fr/problems/rpm-faq.tex @@ -0,0 +1,394 @@ +%% +%% + +\chapter{Bacula RPM Packaging FAQ} +\label{RpmFaqChapter} +\index[general]{FAQ!Bacula\textsuperscript{\textregistered} - RPM Packaging } +\index[general]{Bacula\textsuperscript{\textregistered} - RPM Packaging FAQ } + +\begin{enumerate} +\item + \ilink{How do I build Bacula for platform xxx?}{faq1} +\item + \ilink{How do I control which database support gets built?}{faq2} + +\item + \ilink{What other defines are used?}{faq3} +\item + \ilink{I'm getting errors about not having permission when I try to build the + packages. Do I need to be root?}{faq4} +\item + \ilink{I'm building my own rpms but on all platforms and compiles I get an + unresolved dependency for something called + /usr/afsws/bin/pagsh.}{faq5} +\item + \ilink{I'm building my own rpms because you don't publish for my platform. + Can I get my packages released to sourceforge for other people to use?}{faq6} +\item + \ilink{Is there an easier way than sorting out all these command line options?}{faq7} +\item + \ilink{I just upgraded from 1.36.x to 1.38.x and now my director daemon won't start. It appears to start but dies silently and I get a "connection refused" error when starting the console. What is wrong?}{faq8} +\item + \ilink{There are a lot of rpm packages. Which packages do I need for what?}{faq9} +\end{enumerate} + +\section{Answers} +\index[general]{Answers } + +\begin{enumerate} +\item + \label{faq1} + {\bf How do I build Bacula for platform xxx?} + The bacula spec file contains defines to build for several platforms: + Red Hat 7.x (rh7), Red Hat 8.0 (rh8), Red Hat 9 (rh9), Fedora Core (fc1, + fc3, fc4, fc5, fc6, fc7), Whitebox Enterprise Linux 3.0 (wb3), Red Hat Enterprise Linux + (rhel3, rhel4, rhel5), Mandrake 10.x (mdk), Mandriva 2006.x (mdv) CentOS (centos3, centos4, centos5) + Scientific Linux (sl3, sl4, sl5) and SuSE (su9, su10, su102, su103). The package build is controlled by a mandatory define set at the beginning of the file. These defines basically just control the dependency information that gets coded into the finished rpm package as well + as any special configure options required. The platform define may be edited + in the spec file directly (by default all defines are set to 0 or "not set"). + For example, to build the Red Hat 7.x package find the line in the spec file + which reads + +\footnotesize +\begin{verbatim} + %define rh7 0 + +\end{verbatim} +\normalsize + +and edit it to read + +\footnotesize +\begin{verbatim} + %define rh7 1 + +\end{verbatim} +\normalsize + +Alternately you may pass the define on the command line when calling rpmbuild: + + +\footnotesize +\begin{verbatim} + rpmbuild -ba --define "build_rh7 1" bacula.spec + rpmbuild --rebuild --define build_rh7 1" bacula-x.x.x-x.src.rpm + +\end{verbatim} +\normalsize + +\item + \label{faq2} + {\bf How do I control which database support gets built?} + Another mandatory build define controls which database support is compiled, + one of build\_sqlite, build\_mysql or build\_postgresql. To get the MySQL + package and support either set the + +\footnotesize +\begin{verbatim} + %define mysql 0 + OR + %define mysql4 0 + OR + %define mysql5 0 + +\end{verbatim} +\normalsize + +to + +\footnotesize +\begin{verbatim} + %define mysql 1 + OR + %define mysql4 1 + OR + %define mysql5 1 + +\end{verbatim} +\normalsize + +in the spec file directly or pass it to rpmbuild on the command line: + +\footnotesize +\begin{verbatim} + rpmbuild -ba --define "build_rh7 1" --define "build_mysql 1" bacula.spec + rpmbuild -ba --define "build_rh7 1" --define "build_mysql4 1" bacula.spec + rpmbuild -ba --define "build_rh7 1" --define "build_mysql5 1" bacula.spec + +\end{verbatim} +\normalsize + +\item + \label{faq3} + {\bf What other defines are used?} + Three other building defines of note are the depkgs\_version, docs\_version and + \_rescuever identifiers. These two defines are set with each release and must + match the version of those sources that are being used to build the packages. + You would not ordinarily need to edit these. See also the Build Options section + below for other build time options that can be passed on the command line. +\item + \label{faq4} + {\bf I'm getting errors about not having permission when I try to build the + packages. Do I need to be root?} + No, you do not need to be root and, in fact, it is better practice to + build rpm packages as a non-root user. Bacula packages are designed to + be built by a regular user but you must make a few changes on your + system to do this. If you are building on your own system then the + simplest method is to add write permissions for all to the build + directory (/usr/src/redhat/, /usr/src/RPM or /usr/src/packages). + To accomplish this, execute the following command as root: + +\footnotesize +\begin{verbatim} + chmod -R 777 /usr/src/redhat + chmod -R 777 /usr/src/RPM + chmod -R 777 /usr/src/packages + +\end{verbatim} +\normalsize + +If you are working on a shared system where you can not use the method +above then you need to recreate the appropriate above directory tree with all +of its subdirectories inside your home directory. Then create a file named + +{\tt .rpmmacros} + +in your home directory (or edit the file if it already exists) +and add the following line: + +\footnotesize +\begin{verbatim} + %_topdir /home/myuser/redhat + +\end{verbatim} +\normalsize + +Another handy directive for the .rpmmacros file if you wish to suppress the +creation of debug rpm packages is: + +\footnotesize +\begin{verbatim} + %debug_package %{nil} + +\end{verbatim} + +\normalsize + +\item + \label{faq5} + {\bf I'm building my own rpms but on all platforms and compiles I get an + unresolved dependency for something called /usr/afsws/bin/pagsh.} This + is a shell from the OpenAFS (Andrew File System). If you are seeing + this then you chose to include the docs/examples directory in your + package. One of the example scripts in this directory is a pagsh + script. Rpmbuild, when scanning for dependencies, looks at the shebang + line of all packaged scripts in addition to checking shared libraries. + To avoid this do not package the examples directory. If you are seeing this + problem you are building a very old bacula package as the examples have been + removed from the doc packaging. + +\item + \label{faq6} + {\bf I'm building my own rpms because you don't publish for my platform. + Can I get my packages released to sourceforge for other people to use?} Yes, + contributions from users are accepted and appreciated. Please examine the + directory platforms/contrib-rpm in the source code for further information. + +\item + \label{faq7} + {\bf Is there an easier way than sorting out all these command line options?} Yes, + there is a gui wizard shell script which you can use to rebuild the src rpm package. + Look in the source archive for platforms/contrib-rpm/rpm\_wizard.sh. This script will + allow you to specify build options using GNOME dialog screens. It requires zenity. + +\item + \label{faq8} + {\bf I just upgraded from 1.36.x to 1.38.x and now my director daemon +won't start. It appears to start but dies silently and I get a "connection +refused" error when starting the console. What is wrong?} Beginning with +1.38 the rpm packages are configured to run the director and storage +daemons as a non-root user. The file daemon runs as user root and group +bacula, the storage daemon as user bacula and group disk, and the director +as user bacula and group bacula. If you are upgrading you will need to +change some file permissions for things to work. Execute the following +commands as root: + +\footnotesize +\begin{verbatim} + chown bacula.bacula /var/bacula/* + chown root.bacula /var/bacula/bacula-fd.9102.state + chown bacula.disk /var/bacula/bacula-sd.9103.state + +\end{verbatim} +\normalsize + +Further, if you are using File storage volumes rather than tapes those +files will also need to have ownership set to user bacula and group bacula. + +\item + \label{faq9} + {\bf There are a lot of rpm packages. Which packages do I need for +what?} For a bacula server you need to select the packsge based upon your +preferred catalog database: one of bacula-mysql, bacula-postgresql or +bacula-sqlite. If your system does not provide an mtx package you also +need bacula-mtx to satisfy that dependancy. For a client machine you need +only install bacula-client. Optionally, for either server or client +machines, you may install a graphical console bacula-gconsole and/or +bacula-wxconsole. The Bacula Administration Tool is installed with the +bacula-bat package. One last package, bacula-updatedb is required only when +upgrading a server more than one database revision level. + + + +\item {\bf Support for RHEL3/4/5, CentOS 3/4/5, Scientific Linux 3/4/5 and x86\_64} + The examples below show + explicit build support for RHEL4 and CentOS 4. Build support + for x86\_64 has also been added. +\end{enumerate} + +\footnotesize +\begin{verbatim} +Build with one of these 3 commands: + +rpmbuild --rebuild \ + --define "build_rhel4 1" \ + --define "build_sqlite 1" \ + bacula-1.38.3-1.src.rpm + +rpmbuild --rebuild \ + --define "build_rhel4 1" \ + --define "build_postgresql 1" \ + bacula-1.38.3-1.src.rpm + +rpmbuild --rebuild \ + --define "build_rhel4 1" \ + --define "build_mysql4 1" \ + bacula-1.38.3-1.src.rpm + +For CentOS substitute '--define "build_centos4 1"' in place of rhel4. +For Scientific Linux substitute '--define "build_sl4 1"' in place of rhel4. + +For 64 bit support add '--define "build_x86_64 1"' +\end{verbatim} +\normalsize + +\section{Build Options} +\index[general]{Build Options} +The spec file currently supports building on the following platforms: +\footnotesize +\begin{verbatim} +Red Hat builds +--define "build_rh7 1" +--define "build_rh8 1" +--define "build_rh9 1" + +Fedora Core build +--define "build_fc1 1" +--define "build_fc3 1" +--define "build_fc4 1" +--define "build_fc5 1" +--define "build_fc6 1" +--define "build_fc7 1" + +Whitebox Enterprise build +--define "build_wb3 1" + +Red Hat Enterprise builds +--define "build_rhel3 1" +--define "build_rhel4 1" +--define "build_rhel5 1" + +CentOS build +--define "build_centos3 1" +--define "build_centos4 1" +--define "build_centos5 1" + +Scientific Linux build +--define "build_sl3 1" +--define "build_sl4 1" +--define "build_sl5 1" + +SuSE build +--define "build_su9 1" +--define "build_su10 1" +--define "build_su102 1" +--define "build_su103 1" + +Mandrake 10.x build +--define "build_mdk 1" + +Mandriva build +--define "build_mdv 1" + +MySQL support: +for mysql 3.23.x support define this +--define "build_mysql 1" +if using mysql 4.x define this, +currently: Mandrake 10.x, Mandriva 2006.0, SuSE 9.x & 10.0, FC4 & RHEL4 +--define "build_mysql4 1" +if using mysql 5.x define this, +currently: SuSE 10.1 & FC5 +--define "build_mysql5 1" + +PostgreSQL support: +--define "build_postgresql 1" + +Sqlite support: +--define "build_sqlite 1" + +Build the client rpm only in place of one of the above database full builds: +--define "build_client_only 1" + +X86-64 support: +--define "build_x86_64 1" + +Supress build of bgnome-console: +--define "nobuild_gconsole 1" + +Build the WXWindows console: +requires wxGTK >= 2.6 +--define "build_wxconsole 1" + +Build the Bacula Administration Tool: +requires QT >= 4.2 +--define "build_bat 1" + +Build python scripting support: +--define "build_python 1" + +Modify the Packager tag for third party packages: +--define "contrib_packager Your Name " + +\end{verbatim} +\normalsize + +\section{RPM Install Problems} +\index[general]{RPM Install Problems} +In general the RPMs, once properly built should install correctly. +However, when attempting to run the daemons, a number of problems +can occur: +\begin{itemize} +\item [Wrong /var/bacula Permissions] + By default, the Director and Storage daemon do not run with + root permission. If the /var/bacula is owned by root, then it + is possible that the Director and the Storage daemon will not + be able to access this directory, which is used as the Working + Directory. To fix this, the easiest thing to do is: +\begin{verbatim} + chown bacula:bacula /var/bacula +\end{verbatim} + Note: as of 1.38.8 /var/bacula is installed root:bacula with + permissions 770. +\item [The Storage daemon cannot Access the Tape drive] + This can happen in some older RPM releases where the Storage + daemon ran under userid bacula, group bacula. There are two + ways of fixing this: the best is to modify the /etc/init.d/bacula-sd + file so that it starts the Storage daemon with group "disk". + The second way to fix the problem is to change the permissions + of your tape drive (usually /dev/nst0) so that Bacula can access it. + You will probably need to change the permissions of the SCSI control + device as well, which is usually /dev/sg0. The exact names depend + on your configuration, please see the Tape Testing chapter for + more information on devices. +\end{itemize} + diff --git a/docs/manuals/fr/problems/setup.sm b/docs/manuals/fr/problems/setup.sm new file mode 100644 index 00000000..7c88dc61 --- /dev/null +++ b/docs/manuals/fr/problems/setup.sm @@ -0,0 +1,23 @@ +/* + * html2latex + */ + +available { + sun4_sunos.4 + sun4_solaris.2 + rs_aix.3 + rs_aix.4 + sgi_irix +} + +description { + From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX +} + +install { + bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex + bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag + bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag + bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag + man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1 +} diff --git a/docs/manuals/fr/problems/tapetesting.tex b/docs/manuals/fr/problems/tapetesting.tex new file mode 100644 index 00000000..7281f34e --- /dev/null +++ b/docs/manuals/fr/problems/tapetesting.tex @@ -0,0 +1,1293 @@ +%% +%% + +\chapter{Testing Your Tape Drive With Bacula} +\label{TapeTestingChapter} +\index[general]{Testing Your Tape Drive With Bacula} + +This chapter is concerned with testing and configuring your tape drive to make +sure that it will work properly with Bacula using the {\bf btape} program. +\label{summary} + +\section{Get Your Tape Drive Working} + +In general, you should follow the following steps to get your tape drive to +work with Bacula. Start with a tape mounted in your drive. If you have an +autochanger, load a tape into the drive. We use {\bf /dev/nst0} as the tape +drive name, you will need to adapt it according to your system. + +Do not proceed to the next item until you have succeeded with the previous +one. + +\begin{enumerate} +\item Make sure that Bacula (the Storage daemon) is not running + or that you have {\bf unmount}ed the drive you will use + for testing. + +\item Use tar to write to, then read from your drive: + + \footnotesize +\begin{verbatim} + mt -f /dev/nst0 rewind + tar cvf /dev/nst0 . + mt -f /dev/nst0 rewind + tar tvf /dev/nst0 + +\end{verbatim} +\normalsize + +\item Make sure you have a valid and correct Device resource corresponding + to your drive. For Linux users, generally, the default one works. For + FreeBSD users, there are two possible Device configurations (see below). + For other drives and/or OSes, you will need to first ensure that your + system tape modes are properly setup (see below), then possibly modify + you Device resource depending on the output from the btape program (next + item). When doing this, you should consult the \ilink{Storage Daemon + Configuration}{StoredConfChapter} of this manual. + +\item If you are using a Fibre Channel to connect your tape drive to + Bacula, please be sure to disable any caching in the NSR (network + storage router, which is a Fibre Channel to SCSI converter). + +\item Run the btape {\bf test} command: + + \footnotesize +\begin{verbatim} + ./btape -c bacula-sd.conf /dev/nst0 + test + +\end{verbatim} +\normalsize + + It isn't necessary to run the autochanger part of the test at this time, + but do not go past this point until the basic test succeeds. If you do + have an autochanger, please be sure to read the \ilink{Autochanger + chapter}{AutochangersChapter} of this manual. + +\item Run the btape {\bf fill} command, preferably with two volumes. This + can take a long time. If you have an autochanger and it is configured, Bacula + will automatically use it. If you do not have it configured, you can manually + issue the appropriate {\bf mtx} command, or press the autochanger buttons to + change the tape when requested to do so. + +\item FreeBSD users, if you have a pre-5.0 system run the {\bf tapetest} + program, and make sure your system is patched if necessary. The tapetest + program can be found in the platform/freebsd directory. The instructions + for its use are at the top of the file. + +\item Run Bacula, and backup a reasonably small directory, say 60 + Megabytes. Do three successive backups of this directory. + +\item Stop Bacula, then restart it. Do another full backup of the same + directory. Then stop and restart Bacula. + +\item Do a restore of the directory backed up, by entering the following + restore command, being careful to restore it to an alternate location: + + +\footnotesize +\begin{verbatim} + restore select all done + yes + +\end{verbatim} +\normalsize + + Do a {\bf diff} on the restored directory to ensure it is identical to the + original directory. If you are going to backup multiple different systems + (Linux, Windows, Mac, Solaris, FreeBSD, ...), be sure you test the restore + on each system type. + +\item If you have an autochanger, you should now go back to the btape program + and run the autochanger test: + +\footnotesize +\begin{verbatim} + ./btape -c bacula-sd.conf /dev/nst0 + auto + +\end{verbatim} +\normalsize + + Adjust your autochanger as necessary to ensure that it works correctly. See + the Autochanger chapter of this manual for a complete discussion of testing + your autochanger. + +\item We strongly recommend that you use a dedicated SCSI + controller for your tape drives. Scanners are known to induce + serious problems with the SCSI bus, causing it to reset. If the + SCSI bus is reset while Bacula has the tape drive open, it will + most likely be fatal to your tape since the drive will rewind. + These kinds of problems show up in the system log. For example, + the following was most likely caused by a scanner: + +\footnotesize +\begin{verbatim} +Feb 14 17:29:55 epohost kernel: (scsi0:A:2:0): No or incomplete CDB sent to device. +Feb 14 17:29:55 epohost kernel: scsi0: Issued Channel A Bus Reset. 1 SCBs aborted +\end{verbatim} +\normalsize + +\end{enumerate} + +If you have reached this point, you stand a good chance of having everything +work. If you get into trouble at any point, {\bf carefully} read the +documentation given below. If you cannot get past some point, ask the {\bf +bacula-users} email list, but specify which of the steps you have successfully +completed. In particular, you may want to look at the +\ilink{ Tips for Resolving Problems}{problems1} section below. + + +\label{NoTapeInDrive} +\subsection{Problems When no Tape in Drive} +\index[general]{Problems When no Tape in Drive} +When Bacula was first written the Linux 2.4 kernel permitted opening the +drive whether or not there was a tape in the drive. Thus the Bacula code is +based on the concept that if the drive cannot be opened, there is a serious +problem, and the job is failed. + +With version 2.6 of the Linux kernel, if there is no tape in the drive, the +OS will wait two minutes (default) and then return a failure, and consequently, +Bacula version 1.36 and below will fail the job. This is important to keep +in mind, because if you use an option such as {\bf Offline on Unmount = +yes}, there will be a point when there is no tape in the drive, and if +another job starts or if Bacula asks the operator to mount a tape, when +Bacula attempts to open the drive (about a 20 minute delay), it will fail +and Bacula will fail the job. + +In version 1.38.x, the Bacula code partially gets around this problem -- at +least in the initial open of the drive. However, functions like Polling +the drive do not work correctly if there is no tape in the drive. +Providing you do not use {\bf Offline on Unmount = yes}, you should not +experience job failures as mentioned above. If you do experience such +failures, you can also increase the {\bf Maximum Open Wait} time interval, +which will give you more time to mount the next tape before the job is +failed. + +\subsection{Specifying the Configuration File} +\index[general]{File!Specifying the Configuration} +\index[general]{Specifying the Configuration File} + +Starting with version 1.27, each of the tape utility programs including the +{\bf btape} program requires a valid Storage daemon configuration file +(actually, the only part of the configuration file that {\bf btape} needs is +the {\bf Device} resource definitions). This permits {\bf btape} to find the +configuration parameters for your archive device (generally a tape drive). +Without those parameters, the testing and utility programs do not know how to +properly read and write your drive. By default, they use {\bf bacula-sd.conf} +in the current directory, but you may specify a different configuration file +using the {\bf -c} option. + +\subsection{Specifying a Device Name For a Tape} +\index[general]{Tape!Specifying a Device Name For a} +\index[general]{Specifying a Device Name For a Tape} + +{\bf btape} {\bf device-name} where the Volume can be found. In the case of a +tape, this is the physical device name such as {\bf /dev/nst0} or {\bf +/dev/rmt/0ubn} depending on your system that you specify on the Archive Device +directive. For the program to work, it must find the identical name in the +Device resource of the configuration file. If the name is not found in the +list of physical names, the utility program will compare the name you entered +to the Device names (rather than the Archive device names). + +When specifying a tape device, it is preferable that the "non-rewind" +variant of the device file name be given. In addition, on systems such as +Sun, which have multiple tape access methods, you must be sure to specify +to use Berkeley I/O conventions with the device. The +{\bf b} in the Solaris (Sun) archive specification {\bf /dev/rmt/0mbn} is +what is needed in this case. Bacula does not support SysV tape drive +behavior. + +See below for specifying Volume names. + +\subsection{Specifying a Device Name For a File} +\index[general]{File!Specifying a Device Name For a} +\index[general]{Specifying a Device Name For a File} + +If you are attempting to read or write an archive file rather than a tape, the +{\bf device-name} should be the full path to the archive location including +the filename. The filename (last part of the specification) will be stripped +and used as the Volume name, and the path (first part before the filename) +must have the same entry in the configuration file. So, the path is equivalent +to the archive device name, and the filename is equivalent to the volume name. + + +\section{btape} +\label{btape1} +\index[general]{Btape} + +This program permits a number of elementary tape operations via a tty command +interface. The {\bf test} command, described below, can be very useful for +testing tape drive compatibility problems. Aside from initial testing of tape +drive compatibility with {\bf Bacula}, {\bf btape} will be mostly used by +developers writing new tape drivers. + +{\bf btape} can be dangerous to use with existing {\bf Bacula} tapes because +it will relabel a tape or write on the tape if so requested regardless of +whether or not the tape contains valuable data, so please be careful and use +it only on blank tapes. + +To work properly, {\bf btape} needs to read the Storage daemon's configuration +file. As a default, it will look for {\bf bacula-sd.conf} in the current +directory. If your configuration file is elsewhere, please use the {\bf -c} +option to specify where. + +The physical device name or the Device resource name must be specified on the +command line, and this same device name must be present in the Storage +daemon's configuration file read by {\bf btape} + +\footnotesize +\begin{verbatim} +Usage: btape [options] device_name + -b specify bootstrap file + -c set configuration file to file + -d set debug level to nn + -p proceed inspite of I/O errors + -s turn off signals + -v be verbose + -? print this message. +\end{verbatim} +\normalsize + +\subsection{Using btape to Verify your Tape Drive} +\index[general]{Using btape to Verify your Tape Drive} +\index[general]{Drive!Using btape to Verify your Tape} + +An important reason for this program is to ensure that a Storage daemon +configuration file is defined so that Bacula will correctly read and write +tapes. + +It is highly recommended that you run the {\bf test} command before running +your first Bacula job to ensure that the parameters you have defined for your +storage device (tape drive) will permit {\bf Bacula} to function properly. You +only need to mount a blank tape, enter the command, and the output should be +reasonably self explanatory. For example: + +\footnotesize +\begin{verbatim} +(ensure that Bacula is not running) +./btape -c /usr/bin/bacula/bacula-sd.conf /dev/nst0 +\end{verbatim} +\normalsize + +The output will be: + +\footnotesize +\begin{verbatim} +Tape block granularity is 1024 bytes. +btape: btape.c:376 Using device: /dev/nst0 +* +\end{verbatim} +\normalsize + +Enter the test command: + +\footnotesize +\begin{verbatim} +test +\end{verbatim} +\normalsize + +The output produced should be something similar to the following: I've cut the +listing short because it is frequently updated to have new tests. + +\footnotesize +\begin{verbatim} +=== Append files test === +This test is essential to Bacula. +I'm going to write one record in file 0, + two records in file 1, + and three records in file 2 +btape: btape.c:387 Rewound /dev/nst0 +btape: btape.c:855 Wrote one record of 64412 bytes. +btape: btape.c:857 Wrote block to device. +btape: btape.c:410 Wrote EOF to /dev/nst0 +btape: btape.c:855 Wrote one record of 64412 bytes. +btape: btape.c:857 Wrote block to device. +btape: btape.c:855 Wrote one record of 64412 bytes. +btape: btape.c:857 Wrote block to device. +btape: btape.c:410 Wrote EOF to /dev/nst0 +btape: btape.c:855 Wrote one record of 64412 bytes. +btape: btape.c:857 Wrote block to device. +btape: btape.c:855 Wrote one record of 64412 bytes. +btape: btape.c:857 Wrote block to device. +btape: btape.c:855 Wrote one record of 64412 bytes. +btape: btape.c:857 Wrote block to device. +btape: btape.c:410 Wrote EOF to /dev/nst0 +btape: btape.c:387 Rewound /dev/nst0 +btape: btape.c:693 Now moving to end of media. +btape: btape.c:427 Moved to end of media +We should be in file 3. I am at file 3. This is correct! +Now the important part, I am going to attempt to append to the tape. +... +=== End Append files test === +\end{verbatim} +\normalsize + +If you do not successfully complete the above test, please resolve the +problem(s) before attempting to use {\bf Bacula}. Depending on your tape +drive, the test may recommend that you add certain records to your +configuration. We strongly recommend that you do so and then re-run the above +test to insure it works the first time. + +Some of the suggestions it provides for resolving the problems may or may not +be useful. If at all possible avoid using fixed blocking. If the test suddenly +starts to print a long series of: + +\footnotesize +\begin{verbatim} +Got EOF on tape. +Got EOF on tape. +... +\end{verbatim} +\normalsize + +then almost certainly, you are running your drive in fixed block mode rather +than variable block mode. See below for more help of resolving fix +versus variable block problems. + +It is also possible that you have your drive +set in SysV tape drive mode. The drive must use BSD tape conventions. +See the section above on setting your {\bf Archive device} correctly. + +For FreeBSD users, please see the notes below for doing further testing of +your tape drive. + +\label{SCSITricks} +\subsection{Linux SCSI Tricks} +\index[general]{Tricks!Linux SCSI} +\index[general]{Linux SCSI Tricks} + +You can find out what SCSI devices you have by doing: + +\footnotesize +\begin{verbatim} +lsscsi +\end{verbatim} +\normalsize + +Typical output is: + +\footnotesize +\begin{verbatim} +[0:0:0:0] disk ATA ST3160812AS 3.AD /dev/sda +[2:0:4:0] tape HP Ultrium 2-SCSI F6CH /dev/st0 +[2:0:5:0] tape HP Ultrium 2-SCSI F6CH /dev/st1 +[2:0:6:0] mediumx OVERLAND LXB 0107 - +[2:0:9:0] tape HP Ultrium 1-SCSI E50H /dev/st2 +[2:0:10:0] mediumx OVERLAND LXB 0107 - +\end{verbatim} +\normalsize + +There are two drives in one autochanger: /dev/st0 and /dev/st1 +and a third tape drive at /dev/st2. For using them with Bacula, one +would normally reference them as /dev/nst0 ... /dev/nst2. Not also, +there are two different autochangers identified as "mediumx OVERLAND LXB". +They can be addressed via their /dev/sgN designation, which can be +obtained by counting from the beginning as 0 to each changer. In the +above case, the two changers are located on /dev/sg3 and /dev/sg5. The one +at /dev/sg3, controls drives /dev/nst0 and /dev/nst1; and the one at +/dev/sg5 controles drive /dev/nst2. + +If you do not have the {\bf lsscsi} command, you can obtain the same +information as follows: + +\footnotesize +\begin{verbatim} +cat /proc/scsi/scsi +\end{verbatim} +\normalsize + +For the above example with the three drives and two autochangers, +I get: + +\footnotesize +\begin{verbatim} +Attached devices: +Host: scsi0 Channel: 00 Id: 00 Lun: 00 + Vendor: ATA Model: ST3160812AS Rev: 3.AD + Type: Direct-Access ANSI SCSI revision: 05 +Host: scsi2 Channel: 00 Id: 04 Lun: 00 + Vendor: HP Model: Ultrium 2-SCSI Rev: F6CH + Type: Sequential-Access ANSI SCSI revision: 03 +Host: scsi2 Channel: 00 Id: 05 Lun: 00 + Vendor: HP Model: Ultrium 2-SCSI Rev: F6CH + Type: Sequential-Access ANSI SCSI revision: 03 +Host: scsi2 Channel: 00 Id: 06 Lun: 00 + Vendor: OVERLAND Model: LXB Rev: 0107 + Type: Medium Changer ANSI SCSI revision: 02 +Host: scsi2 Channel: 00 Id: 09 Lun: 00 + Vendor: HP Model: Ultrium 1-SCSI Rev: E50H + Type: Sequential-Access ANSI SCSI revision: 03 +Host: scsi2 Channel: 00 Id: 10 Lun: 00 + Vendor: OVERLAND Model: LXB Rev: 0107 + Type: Medium Changer ANSI SCSI revision: 02 +\end{verbatim} +\normalsize + + +As an additional example, I get the following (on a different machine from the +above example): + +\footnotesize +\begin{verbatim} +Attached devices: +Host: scsi2 Channel: 00 Id: 01 Lun: 00 + Vendor: HP Model: C5713A Rev: H107 + Type: Sequential-Access ANSI SCSI revision: 02 +Host: scsi2 Channel: 00 Id: 04 Lun: 00 + Vendor: SONY Model: SDT-10000 Rev: 0110 + Type: Sequential-Access ANSI SCSI revision: 02 +\end{verbatim} +\normalsize + +The above represents first an autochanger and second a simple +tape drive. The HP changer (the first entry) uses the same SCSI channel +for data and for control, so in Bacula, you would use: +\footnotesize +\begin{verbatim} +Archive Device = /dev/nst0 +Changer Device = /dev/sg0 +\end{verbatim} +\normalsize + +If you want to remove the SDT-10000 device, you can do so as root with: + +\footnotesize +\begin{verbatim} +echo "scsi remove-single-device 2 0 4 0">/proc/scsi/scsi +\end{verbatim} +\normalsize + +and you can put add it back with: + +\footnotesize +\begin{verbatim} +echo "scsi add-single-device 2 0 4 0">/proc/scsi/scsi +\end{verbatim} +\normalsize + +where the 2 0 4 0 are the Host, Channel, Id, and Lun as seen on the output +from {\bf cat /proc/scsi/scsi}. Note, the Channel must be specified as +numeric. + +Below is a slightly more complicated output, which is a single autochanger +with two drives, and which operates the changer on a different channel +from from the drives: + +\footnotesize +\begin{verbatim} +Attached devices: +Host: scsi0 Channel: 00 Id: 00 Lun: 00 + Vendor: ATA Model: WDC WD1600JD-75H Rev: 08.0 + Type: Direct-Access ANSI SCSI revision: 05 +Host: scsi2 Channel: 00 Id: 04 Lun: 00 + Vendor: HP Model: Ultrium 2-SCSI Rev: F6CH + Type: Sequential-Access ANSI SCSI revision: 03 +Host: scsi2 Channel: 00 Id: 05 Lun: 00 + Vendor: HP Model: Ultrium 2-SCSI Rev: F6CH + Type: Sequential-Access ANSI SCSI revision: 03 +Host: scsi2 Channel: 00 Id: 06 Lun: 00 + Vendor: OVERLAND Model: LXB Rev: 0106 + Type: Medium Changer ANSI SCSI revision: 02 +\end{verbatim} +\normalsize + +The above tape drives are accessed on /dev/nst0 and /dev/nst1, while +the control channel for those two drives is /dev/sg3. + + + +\label{problems1} +\section{Tips for Resolving Problems} +\index[general]{Problems!Tips for Resolving} +\index[general]{Tips for Resolving Problems} + +\label{CannotRestore} +\subsection{Bacula Saves But Cannot Restore Files} +\index[general]{Files!Bacula Saves But Cannot Restore} +\index[general]{Bacula Saves But Cannot Restore Files} + +If you are getting error messages such as: + +\footnotesize +\begin{verbatim} +Volume data error at 0:1! Wanted block-id: "BB02", got "". Buffer discarded +\end{verbatim} +\normalsize + +It is very likely that Bacula has tried to do block positioning and ended up +at an invalid block. This can happen if your tape drive is in fixed block mode +while Bacula's default is variable blocks. Note that in such cases, Bacula is +perfectly able to write to your Volumes (tapes), but cannot position to read +them. + +There are two possible solutions. + +\begin{enumerate} +\item The first and best is to always ensure that your drive is in variable + block mode. Note, it can switch back to fixed block mode on a reboot or if + another program uses the drive. So on such systems you need to modify the + Bacula startup files to explicitly set: + +\footnotesize +\begin{verbatim} +mt -f /dev/nst0 defblksize 0 +\end{verbatim} +\normalsize + +or whatever is appropriate on your system. Note, if you are running a Linux +system, and the above command does not work, it is most likely because you +have not loaded the appropriate {\bf mt} package, which is often called +{\bf mt\_st}, but may differ according to your distribution. + +\item The second possibility, especially, if Bacula wrote while the drive was + in fixed block mode, is to turn off block positioning in Bacula. This is done + by adding: + +\footnotesize +\begin{verbatim} +Block Positioning = no +\end{verbatim} +\normalsize + +to the Device resource. This is not the recommended procedure because it can +enormously slow down recovery of files, but it may help where all else +fails. This directive is available in version 1.35.5 or later (and not yet +tested). +\end{enumerate} + +If you are getting error messages such as: +\footnotesize +\begin{verbatim} +Volume data error at 0:0! +Block checksum mismatch in block=0 len=32625 calc=345678 blk=123456 +\end{verbatim} +\normalsize + +You are getting tape read errors, and this is most likely due to +one of the following things: +\begin{enumerate} +\item An old or bad tape. +\item A dirty drive that needs cleaning (particularly for DDS drives). +\item A loose SCSI cable. +\item Old firmware in your drive. Make sure you have the latest firmware + loaded. +\item Computer memory errors. +\item Over-clocking your CPU. +\item A bad SCSI card. +\end{enumerate} + + +\label{opendevice} +\subsection{Bacula Cannot Open the Device} +\index[general]{Device!Bacula Cannot Open the} +\index[general]{Bacula Cannot Open the Device} + +If you get an error message such as: + +\footnotesize +\begin{verbatim} +dev open failed: dev.c:265 stored: unable to open +device /dev/nst0:> ERR=No such device or address +\end{verbatim} +\normalsize + +the first time you run a job, it is most likely due to the fact that you +specified the incorrect device name on your {\bf Archive Device}. + +If Bacula works fine with your drive, then all off a sudden you get error +messages similar to the one shown above, it is quite possible that your driver +module is being removed because the kernel deems it idle. This is done via +{\bf crontab} with the use of {\bf rmmod -a}. To fix the problem, you can +remove this entry from {\bf crontab}, or you can manually {\bf modprob} your +driver module (or add it to the local startup script). Thanks to Alan Brown +for this tip. +\label{IncorrectFiles} + +\subsection{Incorrect File Number} +\index[general]{Number!Incorrect File} +\index[general]{Incorrect File Number} + +When Bacula moves to the end of the medium, it normally uses the {\bf +ioctl(MTEOM)} function. Then Bacula uses the {\bf ioctl(MTIOCGET)} function to +retrieve the current file position from the {\bf mt\_fileno} field. Some SCSI +tape drivers will use a fast means of seeking to the end of the medium and in +doing so, they will not know the current file position and hence return a {\bf +-1}. As a consequence, if you get {\bf "This is NOT correct!"} in the +positioning tests, this may be the cause. You must correct this condition in +order for Bacula to work. + +There are two possible solutions to the above problem of incorrect file +number: + +\begin{itemize} +\item Figure out how to configure your SCSI driver to keep track of the file + position during the MTEOM request. This is the preferred solution. +\item Modify the {\bf Device} resource of your {\bf bacula-sd.conf} file to + include: + +\footnotesize +\begin{verbatim} +Hardware End of File = no +\end{verbatim} +\normalsize + +This will cause Bacula to use the MTFSF request to seek to the end of the +medium, and Bacula will keep track of the file number itself. +\end{itemize} + +\label{IncorrectBlocks} +\subsection{Incorrect Number of Blocks or Positioning Errors} +\index[general]{Testing!Incorrect Number of Blocks or Positioning Errors} +\index[general]{Incorrect Number of Blocks or Positioning Errors} + +{\bf Bacula's} preferred method of working with tape drives (sequential +devices) is to run in variable block mode, and this is what is set by default. +You should first ensure that your tape drive is set for variable block mode +(see below). + +If your tape drive is in fixed block mode and you have told Bacula to use +different fixed block sizes or variable block sizes (default), you will get +errors when Bacula attempts to forward space to the correct block (the kernel +driver's idea of tape blocks will not correspond to Bacula's). + +All modern tape drives support variable tape blocks, but some older drives (in +particular the QIC drives) as well as the ATAPI ide-scsi driver run only in +fixed block mode. The Travan tape drives also apparently must run in fixed +block mode (to be confirmed). + +Even in variable block mode, with the exception of the first record on the +second or subsequent volume of a multi-volume backup, Bacula will write blocks +of a fixed size. However, in reading a tape, Bacula will assume that for each +read request, exactly one block from the tape will be transferred. This the +most common way that tape drives work and is well supported by {\bf Bacula}. + +Drives that run in fixed block mode can cause serious problems for Bacula if +the drive's block size does not correspond exactly to {\bf Bacula's} block +size. In fixed block size mode, drivers may transmit a partial block or +multiple blocks for a single read request. From {\bf Bacula's} point of view, +this destroys the concept of tape blocks. It is much better to run in variable +block mode, and almost all modern drives (the OnStream is an exception) run in +variable block mode. In order for Bacula to run in fixed block mode, you must +include the following records in the Storage daemon's Device resource +definition: + +\footnotesize +\begin{verbatim} +Minimum Block Size = nnn +Maximum Block Size = nnn +\end{verbatim} +\normalsize + +where {\bf nnn} must be the same for both records and must be identical to the +driver's fixed block size. + +We recommend that you avoid this configuration if at all possible by using +variable block sizes. + +If you must run with fixed size blocks, make sure they are not 512 bytes. This +is too small and the overhead that Bacula has with each record will become +excessive. If at all possible set any fixed block size to something like +64,512 bytes or possibly 32,768 if 64,512 is too large for your drive. See +below for the details on checking and setting the default drive block size. + +To recover files from tapes written in fixed block mode, see below. + +\label{TapeModes} +\subsection{Ensuring that the Tape Modes Are Properly Set -- {\bf Linux +Only}} +\index[general]{Ensuring that the Tape Modes Are Properly Set -- Linux Only} + +If you have a modern SCSI tape drive and you are having problems with the {\bf +test} command as noted above, it may be that some program has set one or more +of your SCSI driver's options to non-default values. For example, if your +driver is set to work in SysV manner, Bacula will not work correctly because +it expects BSD behavior. To reset your tape drive to the default values, you +can try the following, but {\bf ONLY} if you have a SCSI tape drive on a {\bf +Linux} system: + +\footnotesize +\begin{verbatim} +become super user +mt -f /dev/nst0 rewind +mt -f /dev/nst0 stoptions buffer-writes async-writes read-ahead +\end{verbatim} +\normalsize + +The above commands will clear all options and then set those specified. None +of the specified options are required by Bacula, but a number of other options +such as SysV behavior must not be set. Bacula does not support SysV tape +behavior. On systems other than Linux, you will need to consult your {\bf mt} +man pages or documentation to figure out how to do the same thing. This should +not really be necessary though -- for example, on both Linux and Solaris +systems, the default tape driver options are compatible with Bacula. +On Solaris systems, you must take care to specify the correct device +name on the {\bf Archive device} directive. See above for more details. + +You may also want to ensure that no prior program has set the default block +size, as happened to one user, by explicitly turning it off with: + +\footnotesize +\begin{verbatim} +mt -f /dev/nst0 defblksize 0 +\end{verbatim} +\normalsize + +If you are running a Linux +system, and the above command does not work, it is most likely because you +have not loaded the appropriate {\bf mt} package, which is often called +{\bf mt\_st}, but may differ according to your distribution. + +If you would like to know what options you have set before making any of the +changes noted above, you can now view them on Linux systems, thanks to a tip +provided by Willem Riede. Do the following: + +\footnotesize +\begin{verbatim} +become super user +mt -f /dev/nst0 stsetoptions 0 +grep st0 /var/log/messages +\end{verbatim} +\normalsize + +and you will get output that looks something like the following: + +\footnotesize +\begin{verbatim} +kernel: st0: Mode 0 options: buffer writes: 1, async writes: 1, read ahead: 1 +kernel: st0: can bsr: 0, two FMs: 0, fast mteom: 0, auto lock: 0, +kernel: st0: defs for wr: 0, no block limits: 0, partitions: 0, s2 log: 0 +kernel: st0: sysv: 0 nowait: 0 +\end{verbatim} +\normalsize + +Note, I have chopped off the beginning of the line with the date and machine +name for presentation purposes. + +Some people find that the above settings only last until the next reboot, so +please check this otherwise you may have unexpected problems. + +Beginning with Bacula version 1.35.8, if Bacula detects that you are running +in variable block mode, it will attempt to set your drive appropriately. All +OSes permit setting variable block mode, but some OSes do not permit setting +the other modes that Bacula needs to function properly. + +\label{compression} +\subsection{Tape Hardware Compression and Blocking Size} +\index[general]{Tape Hardware Compression and Blocking Size} +\index[general]{Size!Tape Hardware Compression and Blocking Size} + +As far as I can tell, there is no way with the {\bf mt} program to check if +your tape hardware compression is turned on or off. You can, however, turn it +on by using (on Linux): + +\footnotesize +\begin{verbatim} +become super user +mt -f /dev/nst0 defcompression 1 +\end{verbatim} +\normalsize + +and of course, if you use a zero instead of the one at the end, you will turn +it off. + +If you have built the {\bf mtx} program in the {\bf depkgs} package, you can +use tapeinfo to get quite a bit of information about your tape drive even if +it is not an autochanger. This program is called using the SCSI control +device. On Linux for tape drive /dev/nst0, this is usually /dev/sg0, while on +FreeBSD for /dev/nsa0, the control device is often /dev/pass2. For example on +my DDS-4 drive (/dev/nst0), I get the following: + +\footnotesize +\begin{verbatim} +tapeinfo -f /dev/sg0 +Product Type: Tape Drive +Vendor ID: 'HP ' +Product ID: 'C5713A ' +Revision: 'H107' +Attached Changer: No +MinBlock:1 +MaxBlock:16777215 +SCSI ID: 5 +SCSI LUN: 0 +Ready: yes +BufferedMode: yes +Medium Type: Not Loaded +Density Code: 0x26 +BlockSize: 0 +\end{verbatim} +\normalsize + +where the {\bf DataCompEnabled: yes} means that tape hardware compression is +turned on. You can turn it on and off (yes|no) by using the {\bf mt} +commands given above. Also, this output will tell you if the {\bf BlockSize} +is non-zero and hence set for a particular block size. Bacula is not likely to +work in such a situation because it will normally attempt to write blocks of +64,512 bytes, except the last block of the job which will generally be +shorter. The first thing to try is setting the default block size to zero +using the {\bf mt -f /dev/nst0 defblksize 0} command as shown above. +On FreeBSD, this would be something like: {\bf mt -f /dev/nsa0 blocksize 0}. + +On some operating systems with some tape drives, the amount of data that +can be written to the tape and whether or not compression is enabled is +determined by the density usually the {\bf mt -f /dev/nst0 setdensity xxx} command. +Often {\bf mt -f /dev/nst0 status} will print out the current +density code that is used with the drive. Most systems, but unfortunately +not all, set the density to the maximum by default. On some systems, you +can also get a list of all available density codes with: +{\bf mt -f /dev/nst0 densities} or a similar {\bf mt} command. +Note, for DLT and SDLT devices, no-compression versus compression is very +often controlled by the density code. On FreeBSD systems, the compression +mode is set using {\bf mt -f /dev/nsa0 comp xxx} where xxx is the +mode you want. In general, see {\bf man mt} for the options available on +your system. + +Note, some of the above {\bf mt} commands may not be persistent depending +on your system configuration. That is they may be reset if a program +other than Bacula uses the drive or, as is frequently the case, on reboot +of your system. + +If your tape drive requires fixed block sizes (very unusual), you can use the +following records: + +\footnotesize +\begin{verbatim} +Minimum Block Size = nnn +Maximum Block Size = nnn +\end{verbatim} +\normalsize + +in your Storage daemon's Device resource to force Bacula to write fixed size +blocks (where you sent nnn to be the same for both of the above records). This +should be done only if your drive does not support variable block sizes, or +you have some other strong reasons for using fixed block sizes. As mentioned +above, a small fixed block size of 512 or 1024 bytes will be very inefficient. +Try to set any fixed block size to something like 64,512 bytes or larger if +your drive will support it. + +Also, note that the {\bf Medium Type} field of the output of {\bf tapeinfo} +reports {\bf Not Loaded}, which is not correct. As a consequence, you should +ignore that field as well as the {\bf Attached Changer} field. + +To recover files from tapes written in fixed block mode, see below. +\label{FreeBSDTapes} + +\subsection{Tape Modes on FreeBSD} +\index[general]{FreeBSD!Tape Modes on} +\index[general]{Tape Modes on FreeBSD} + +On most FreeBSD systems such as 4.9 and most tape drives, Bacula should run +with: + +\footnotesize +\begin{verbatim} +mt -f /dev/nsa0 seteotmodel 2 +mt -f /dev/nsa0 blocksize 0 +mt -f /dev/nsa0 comp enable +\end{verbatim} +\normalsize + +You might want to put those commands in a startup script to make sure your +tape driver is properly initialized before running Bacula, because +depending on your system configuration, these modes may be reset if a +program other than Bacula uses the drive or when your system is rebooted. + +Then according to what the {\bf btape test} command returns, you will probably +need to set the following (see below for an alternative): + +\footnotesize +\begin{verbatim} + Hardware End of Medium = no + BSF at EOM = yes + Backward Space Record = no + Backward Space File = no + Fast Forward Space File = no + TWO EOF = yes +\end{verbatim} +\normalsize + +Then be sure to run some append tests with Bacula where you start and stop +Bacula between appending to the tape, or use {\bf btape} version 1.35.1 or +greater, which includes simulation of stopping/restarting Bacula. + +Please see the file {\bf platforms/freebsd/pthreads-fix.txt} in the main +Bacula directory concerning {\bf important} information concerning +compatibility of Bacula and your system. A much more optimal Device +configuration is shown below, but does not work with all tape drives. Please +test carefully before putting either into production. + +Note, for FreeBSD 4.10-RELEASE, using a Sony TSL11000 L100 DDS4 with an +autochanger set to variable block size and DCLZ compression, Brian McDonald +reports that to get Bacula to append correctly between Bacula executions, +the correct values to use are: + +\footnotesize +\begin{verbatim} +mt -f /dev/nsa0 seteotmodel 1 +mt -f /dev/nsa0 blocksize 0 +mt -f /dev/nsa0 comp enable +\end{verbatim} +\normalsize + +and + +\footnotesize +\begin{verbatim} + Hardware End of Medium = no + BSF at EOM = no + Backward Space Record = no + Backward Space File = no + Fast Forward Space File = yes + TWO EOF = no +\end{verbatim} +\normalsize + +This has been confirmed by several other people using different hardware. This +configuration is the preferred one because it uses one EOF and no backspacing +at the end of the tape, which works much more efficiently and reliably with +modern tape drives. + +Finally, here is a Device configuration that Danny Butroyd reports to work +correctly with the Overland Powerloader tape library using LT0-2 and +FreeBSD 5.4-Stable: + +\footnotesize +\begin{verbatim} +# Overland Powerloader LT02 - 17 slots single drive +Device { + Name = Powerloader + Media Type = LT0-2 + Archive Device = /dev/nsa0 + AutomaticMount = yes; + AlwaysOpen = yes; + RemovableMedia = yes; + RandomAccess = no; + Changer Command = "/usr/local/sbin/mtx-changer %c %o %S %a %d" + Changer Device = /dev/pass2 + AutoChanger = yes + Alert Command = "sh -c 'tapeinfo -f %c |grep TapeAlert|cat'" + + # FreeBSD Specific Settings + Offline On Unmount = no + Hardware End of Medium = no + BSF at EOM = yes + Backward Space Record = no + Fast Forward Space File = no + TWO EOF = yes +} + +The following Device resource works fine with Dell PowerVault 110T and +120T devices on both FreeBSD 5.3 and on NetBSD 3.0. It also works +with Sony AIT-2 drives on FreeBSD. +\footnotesize +\begin{verbatim} +Device { + ... + # FreeBSD/NetBSD Specific Settings + Hardware End of Medium = no + BSF at EOM = yes + Backward Space Record = no + Fast Forward Space File = yes + TWO EOF = yes +} +\end{verbatim} +\normalsize + +On FreeBSD version 6.0, it is reported that you can even set +Backward Space Record = yes. + + + +\subsection{Finding your Tape Drives and Autochangers on FreeBSD} +\index[general]{FreeBSD!Finding Tape Drives and Autochangers} +\index[general]{Finding Tape Drives and Autochangers on FreeBSD} + +On FreeBSD, you can do a {\bf camcontrol devlist} as root to determine what +drives and autochangers you have. For example, + +\footnotesize +\begin{verbatim} +undef# camcontrol devlist + at scbus0 target 2 lun 0 (pass0,sa0) + at scbus0 target 4 lun 0 (pass1,sa1) + at scbus0 target 4 lun 1 (pass2) +\end{verbatim} +\normalsize + +from the above, you can determine that there is a tape drive on {\bf /dev/sa0} +and another on {\bf /dev/sa1} in addition since there is a second line for the +drive on {\bf /dev/sa1}, you know can assume that it is the control device for +the autochanger (i.e. {\bf /dev/pass2}). It is also the control device name to +use when invoking the tapeinfo program. E.g. + +\footnotesize +\begin{verbatim} +tapeinfo -f /dev/pass2 +\end{verbatim} +\normalsize + +\label{onstream} + +\subsection{Using the OnStream driver on Linux Systems} +\index[general]{Using the OnStream driver on Linux Systems} +\index[general]{Systems!Using the OnStream driver on Linux} + +Bacula version 1.33 (not 1.32x) is now working and ready for testing with the +OnStream kernel osst driver version 0.9.14 or above. Osst is available from: +\elink{http://sourceforge.net/projects/osst/} +{http://sourceforge.net/projects/osst/}. + +To make Bacula work you must first load the new driver then, as root, do: + +\footnotesize +\begin{verbatim} + mt -f /dev/nosst0 defblksize 32768 +\end{verbatim} +\normalsize + +Also you must add the following to your Device resource in your Storage +daemon's conf file: + +\footnotesize +\begin{verbatim} + Minimum Block Size = 32768 + Maximum Block Size = 32768 +\end{verbatim} +\normalsize + +Here is a Device specification provided by Michel Meyers that is known to +work: + +\footnotesize +\begin{verbatim} +Device { + Name = "Onstream DI-30" + Media Type = "ADR-30" + Archive Device = /dev/nosst0 + Minimum Block Size = 32768 + Maximum Block Size = 32768 + Hardware End of Medium = yes + BSF at EOM = no + Backward Space File = yes + Fast Forward Space File = yes + Two EOF = no + AutomaticMount = yes + AlwaysOpen = yes + Removable Media = yes +} +\end{verbatim} +\normalsize + +\section{Hardware Compression on EXB-8900} +\index[general]{Hardware Compression on EXB-8900} +\index[general]{EXB-8900!Hardware Compression} + +To active, check, or disable the hardware compression feature +on an EXB-8900, use the exabyte MammothTool. You can get it here: +\elink{http://www.exabyte.com/support/online/downloads/index.cfm} +{http://www.exabyte.com/support/online/downloads/index.cfm}. +There is a Solaris version of this tool. With option -C 0 or 1 you +can disable or activate compression. Start this tool without any +options for a small reference. + +\label{fill} +\subsection{Using btape to Simulate Filling a Tape} +\index[general]{Using btape to Simulate Filling a Tape} +\index[general]{Tape!Using btape to Simulate Filling} + +Because there are often problems with certain tape drives or systems when end +of tape conditions occur, {\bf btape} has a special command {\bf fill} that +causes it to write random data to a tape until the tape fills. It then writes +at least one more Bacula block to a second tape. Finally, it reads back both +tapes to ensure that the data has been written in a way that Bacula can +recover it. Note, there is also a single tape option as noted below, which you +should use rather than the two tape test. See below for more details. + +This can be an extremely time consuming process (here it is about 6 hours) to +fill a full tape. Note, that btape writes random data to the tape when it is +filling it. This has two consequences: 1. it takes a bit longer to generate +the data, especially on slow CPUs. 2. the total amount of data is +approximately the real physical capacity of your tape, regardless of whether +or not the tape drive compression is on or off. This is because random data +does not compress very much. + +To begin this test, you enter the {\bf fill} command and follow the +instructions. There are two options: the simple single tape option and the +multiple tape option. Please use only the simple single tape option because +the multiple tape option still doesn't work totally correctly. If the single +tape option does not succeed, you should correct the problem before using +Bacula. +\label{RecoveringFiles} + +\section{Recovering Files Written With Fixed Block Sizes} +\index[general]{Recovering Files Written With Fixed Block Sizes} + +If you have been previously running your tape drive in fixed block mode +(default 512) and Bacula with variable blocks (default), then in version +1.32f-x and 1.34 and above, Bacula will fail to recover files because it does +block spacing, and because the block sizes don't agree between your tape drive +and Bacula it will not work. + +The long term solution is to run your drive in variable block mode as +described above. However, if you have written tapes using fixed block sizes, +this can be a bit of a pain. The solution to the problem is: while you are +doing a restore command using a tape written in fixed block size, ensure that +your drive is set to the fixed block size used while the tape was written. +Then when doing the {\bf restore} command in the Console program, do not +answer the prompt {\bf yes/mod/no}. Instead, edit the bootstrap file (the +location is listed in the prompt) using any ASCII editor. Remove all {\bf +VolBlock} lines in the file. When the file is re-written, answer the question, +and Bacula will run without using block positioning, and it should recover +your files. + +\label{BlockModes} +\section{Tape Blocking Modes} +\index[general]{Modes!Tape Blocking} +\index[general]{Tape Blocking Modes} + +SCSI tapes may either be written in {\bf variable} or {\bf fixed} block sizes. +Newer drives support both modes, but some drives such as the QIC devices +always use fixed block sizes. Bacula attempts to fill and write complete +blocks (default 65K), so that in normal mode (variable block size), Bacula +will always write blocks of the same size except the last block of a Job. If +Bacula is configured to write fixed block sizes, it will pad the last block of +the Job to the correct size. Bacula expects variable tape block size drives to +behave as follows: Each write to the drive results in a single record being +written to the tape. Each read returns a single record. If you request less +bytes than are in the record, only those number of bytes will be returned, but +the entire logical record will have been read (the next read will retrieve the +next record). Thus data from a single write is always returned in a single +read, and sequentially written records are returned by sequential reads. + +Bacula expects fixed block size tape drives to behave as follows: If a write +length is greater than the physical block size of the drive, the write will be +written as two blocks each of the fixed physical size. This single write may +become multiple physical records on the tape. (This is not a good situation). +According to the documentation, one may never write an amount of data that is +not the exact multiple of the blocksize (it is not specified if an error +occurs or if the the last record is padded). When reading, it is my +understanding that each read request reads one physical record from the tape. +Due to the complications of fixed block size tape drives, you should avoid +them if possible with Bacula, or you must be ABSOLUTELY certain that you use +fixed block sizes within Bacula that correspond to the physical block size of +the tape drive. This will ensure that Bacula has a one to one correspondence +between what it writes and the physical record on the tape. + +Please note that Bacula will not function correctly if it writes a block and +that block is split into two or more physical records on the tape. Bacula +assumes that each write causes a single record to be written, and that it can +sequentially recover each of the blocks it has written by using the same +number of sequential reads as it had written. + +\section{Details of Tape Modes} +\index[general]{Modes!Details} +\index[general]{Details of Tape Modes} +Rudolf Cejka has provided the following information concerning +certain tape modes and MTEOM. + +\begin{description} +\item[Tape level] + It is always possible to position filemarks or blocks, whereas + positioning to the end-of-data is only optional feature, however it is + implemented very often. SCSI specification also talks about optional + sequential filemarks, setmarks and sequential setmarks, but these are not + implemented so often. Modern tape drives keep track of file positions in + built-in chip (AIT, LTO) or at the beginning of the tape (SDLT), so there + is not any speed difference, if end-of-data or filemarks is used (I have + heard, that LTO-1 from all 3 manufacturers do not use its chip for file + locations, but a tape as in SDLT case, and I'm not sure about LTO-2 and + LTO-3 case). However there is a big difference, that end-of-data ignores + file position, whereas filemarks returns the real number of skipped + files, so OS can track current file number just in filemarks case. + +\item[OS level] + Solaris does use just SCSI SPACE Filemarks, it does not support SCSI + SPACE End-of-data. When MTEOM is called, Solaris does use SCSI SPACE + Filemarks with count = 1048576 for fast mode, and combination of SCSI + SPACE Filemarks with count = 1 with SCSI SPACE Blocks with count = 1 for + slow mode, so EOD mark on the tape on some older tape drives is not + skipped. File number is always tracked for MTEOM. + + Linux does support both SCSI SPACE Filemarks and End-of-data: When MTEOM + is called in MT\_ST\_FAST\_MTEOM mode, SCSI SPACE End-of-data is used. + In the other case, SCSI SPACE Filemarks with count = + 8388607 is used. + There is no real slow mode like in Solaris - I just expect, that for + older tape drives Filemarks may be slower than End-of-data, but not so + much as in Solaris slow mode. File number is tracked for MTEOM just + without MT\_ST\_FAST\_MTEOM - when MT\_ST\_FAST\_MTEOM is used, it is not. + + FreeBSD does support both SCSI SPACE Filemarks and End-of-data, but when + MTEOD (MTEOM) is called, SCSI SPACE End-of-data is always used. FreeBSD + never use SCSI SPACE Filemarks for MTEOD. File number is never tracked + for MTEOD. + +\item[Bacula level] + When {\bf Hardware End of Medium = Yes} is used, MTEOM is called, but it + does not mean, that hardware End-of-data must be used. When Hardware End + of Medium = No, if Fast Forward Space File = Yes, MTFSF with count = + 32767 is used, else Block Read with count = 1 with Forward Space File + with count = 1 is used, which is really very slow. + +\item [Hardware End of Medium = Yes|No] + The name of this option is misleading and is the source of confusion, + because it is not the hardware EOM, what is really switched here. + + If I use Yes, OS must not use SCSI SPACE End-of-data, because Bacula + expects, that there is tracked file number, which is not supported by + SCSI specification. Instead, the OS have to use SCSI SPACE Filemarks. + + If I use No, an action depends on Fast Forward Space File. + + When I set {\bf Hardware End of Medium = no} + and {\bf Fast Forward Space File = no} + file positioning was very slow + on my LTO-3 (about ten to 100 minutes), but + + with {\bf Hardware End of Medium = no} and +{\bf Fast Forward Space File = yes}, the time is ten to +100 times faster (about one to two minutes). + +\end{description} + +\section{Autochanger Errors} +\index[general]{Errors!Autochanger} +\index[general]{Autochanger Errors} + +If you are getting errors such as: + +\footnotesize +\begin{verbatim} +3992 Bad autochanger "load slot 1, drive 1": ERR=Child exited with code 1. +\end{verbatim} +\normalsize + +and you are running your Storage daemon as non-root, then most likely +you are having permissions problems with the control channel. Running +as root, set permissions on /dev/sgX so that the userid and group of +your Storage daemon can access the device. You need to ensure that you +all access to the proper control device, and if you don't have any +SCSI disk drives (including SATA drives), you might want to change +the permissions on /dev/sg*. + +\section{Syslog Errors} +\index[general]{Errors!Syslog} +\index[general]{Syslog Errors} + +If you are getting errors such as: + +\footnotesize +\begin{verbatim} +: kernel: st0: MTSETDRVBUFFER only allowed for root +\end{verbatim} +\normalsize + +you are most likely running your Storage daemon as non-root, and +Bacula is attempting to set the correct OS buffering to correspond +to your Device resource. Most OSes allow only root to issue this +ioctl command. In general, the message can be ignored providing +you are sure that your OS parameters are properly configured as +described earlier in this manual. If you are running your Storage daemon +as root, you should not be getting these system log messages, and if +you are, something is probably wrong. diff --git a/docs/manuals/fr/problems/tips.tex b/docs/manuals/fr/problems/tips.tex new file mode 100644 index 00000000..d0e77f03 --- /dev/null +++ b/docs/manuals/fr/problems/tips.tex @@ -0,0 +1,1045 @@ +%% +%% + +\chapter{Tips and Suggestions} +\label{TipsChapter} +\index[general]{Tips and Suggestions } +\index[general]{Suggestions!Tips and } +\label{examples} +\index[general]{Examples } + +There are a number of example scripts for various things that can be found in +the {\bf example} subdirectory and its subdirectories of the Bacula source +distribution. + +For additional tips, please see the \elink{Bacula +wiki}{\url{http://wiki.bacula.org}}. + +\section{Upgrading Bacula Versions} +\label{upgrading} +\index[general]{Upgrading Bacula Versions } +\index[general]{Versions!Upgrading Bacula } +\index[general]{Upgrading} + +The first thing to do before upgrading from one version to another is to +ensure that you don't overwrite or delete your production (current) version +of Bacula until you have tested that the new version works. + +If you have installed Bacula into a single directory, this is simple: simply +make a copy of your Bacula directory. + +If you have done a more typical Unix installation where the binaries are +placed in one directory and the configuration files are placed in another, +then the simplest way is to configure your new Bacula to go into a single +file. Alternatively, make copies of all your binaries and especially your +conf files. + +Whatever your situation may be (one of the two just described), you should +probably start with the {\bf defaultconf} script that can be found in the {\bf +examples} subdirectory. Copy this script to the main Bacula directory, modify +it as necessary (there should not need to be many modifications), configure +Bacula, build it, install it, then stop your production Bacula, copy all the +{\bf *.conf} files from your production Bacula directory to the test Bacula +directory, start the test version, and run a few test backups. If all seems +good, then you can proceed to install the new Bacula in place of or possibly +over the old Bacula. + +When installing a new Bacula you need not worry about losing the changes you +made to your configuration files as the installation process will not +overwrite them providing that you do not do a {\bf make uninstall}. + +If the new version of Bacula requires an upgrade to the database, +you can upgrade it with the script {\bf update\_bacula\_tables}, which +will be installed in your scripts directory (default {\bf /etc/bacula}), +or alternatively, you can find it in the +{\bf \lt{}bacula-source\gt{}/src/cats} directory. + +\section{Getting Notified of Job Completion} +\label{notification} +\index[general]{Getting Notified of Job Completion } +\index[general]{Completion!Getting Notified of Job } + +One of the first things you should do is to ensure that you are being properly +notified of the status of each Job run by Bacula, or at a minimum of each Job +that terminates with an error. + +Until you are completely comfortable with {\bf Bacula}, we recommend that you +send an email to yourself for each Job that is run. This is most easily +accomplished by adding an email notification address in the {\bf Messages} +resource of your Director's configuration file. An email is automatically +configured in the default configuration files, but you must ensure that the +default {\bf root} address is replaced by your email address. + +For additional examples of how to configure a Bacula, please take a look at the +{\bf .conf} files found in the {\bf examples} sub-directory. We recommend the +following configuration (where you change the paths and email address to +correspond to your setup). Note, the {\bf mailcommand} and {\bf +operatorcommand} should be on a single line. They were split here for +presentation: + +\footnotesize +\begin{verbatim} +Messages { + Name = Standard + mailcommand = "/home/bacula/bin/bsmtp -h localhost + -f \"\(Bacula\) %r\" + -s \"Bacula: %t %e of %c %l\" %r" + operatorcommand = "/home/bacula/bin/bsmtp -h localhost + -f \"\(Bacula\) %r\" + -s \"Bacula: Intervention needed for %j\" %r" + Mail = your-email-address = all, !skipped, !terminate + append = "/home/bacula/bin/log" = all, !skipped, !terminate + operator = your-email-address = mount + console = all, !skipped, !saved +} +\end{verbatim} +\normalsize + +You will need to ensure that the {\bf /home/bacula/bin} path on the {\bf +mailcommand} and the {\bf operatorcommand} lines point to your {\bf Bacula} +binary directory where the {\bf bsmtp} program will be installed. You will +also want to ensure that the {\bf your-email-address} is replaced by your +email address, and finally, you will also need to ensure that the {\bf +/home/bacula/bin/log} points to the file where you want to log all messages. + +With the above Messages resource, you will be notified by email of every Job +that ran, all the output will be appended to the {\bf log} file you specify, +all output will be directed to the console program, and all mount messages +will be emailed to you. Note, some messages will be sent to multiple +destinations. + +The form of the mailcommand is a bit complicated, but it allows you to +distinguish whether the Job terminated in error or terminated normally. Please +see the +\ilink{Mail Command}{mailcommand} section of the Messages +Resource chapter of this manual for the details of the substitution characters +used above. + +Once you are totally comfortable with Bacula as I am, or if you have a large +number of nightly Jobs as I do (eight), you will probably want to change the +{\bf Mail} command to {\bf Mail On Error} which will generate an email message +only if the Job terminates in error. If the Job terminates normally, no email +message will be sent, but the output will still be appended to the log file as +well as sent to the Console program. + +\section{Getting Email Notification to Work} +\label{email} +\index[general]{Work!Getting Email Notification to } +\index[general]{Getting Email Notification to Work } + +The section above describes how to get email notification of job status. +Occasionally, however, users have problems receiving any email at all. In that +case, the things to check are the following: + +\begin{itemize} +\item Ensure that you have a valid email address specified on your {\bf Mail} + record in the Director's Messages resource. The email address should be fully + qualified. Simply using {\bf root} generally will not work, rather you should +use {\bf root@localhost} or better yet your full domain. +\item Ensure that you do not have a {\bf Mail} record in the Storage daemon's + or File daemon's configuration files. The only record you should have is {\bf + director}: + +\footnotesize +\begin{verbatim} + director = director-name = all + +\end{verbatim} +\normalsize + +\item If all else fails, try replacing the {\bf mailcommand} with + + \footnotesize +\begin{verbatim} +mailcommand = "mail -s test your@domain.com" +\end{verbatim} +\normalsize + +\item Once the above is working, assuming you want to use {\bf bsmtp}, submit + the desired bsmtp command by hand and ensure that the email is delivered, + then put that command into {\bf Bacula}. Small differences in things such as +the parenthesis around the word Bacula can make a big difference to some +bsmtp programs. For example, you might start simply by using: + +\footnotesize +\begin{verbatim} +mailcommand = "/home/bacula/bin/bsmtp -f \"root@localhost\" %r" +\end{verbatim} +\normalsize + +\end{itemize} + +\section{Getting Notified that Bacula is Running} +\label{JobNotification} +\index[general]{Running!Getting Notified that Bacula is } +\index[general]{Getting Notified that Bacula is Running } + +If like me, you have setup Bacula so that email is sent only when a Job has +errors, as described in the previous section of this chapter, inevitably, one +day, something will go wrong and {\bf Bacula} can stall. This could be because +Bacula crashes, which is vary rare, or more likely the network has caused {\bf +Bacula} to {\bf hang} for some unknown reason. + +To avoid this, you can use the {\bf RunAfterJob} command in the Job resource +to schedule a Job nightly, or weekly that simply emails you a message saying +that Bacula is still running. For example, I have setup the following Job in +my Director's configuration file: + +\footnotesize +\begin{verbatim} +Schedule { + Name = "Watchdog" + Run = Level=Full sun-sat at 6:05 +} +Job { + Name = "Watchdog" + Type = Admin + Client=Watchdog + FileSet="Verify Set" + Messages = Standard + Storage = DLTDrive + Pool = Default + Schedule = "Watchdog" + RunAfterJob = "/home/kern/bacula/bin/watchdog %c %d" +} +Client { + Name = Watchdog + Address = rufus + FDPort = 9102 + Catalog = Verify + Password = "" + File Retention = 1day + Job Retention = 1 month + AutoPrune = yes +} +\end{verbatim} +\normalsize + +Where I established a schedule to run the Job nightly. The Job itself is type +{\bf Admin} which means that it doesn't actually do anything, and I've defined +a FileSet, Pool, Storage, and Client, all of which are not really used (and +probably don't need to be specified). The key aspect of this Job is the +command: + +\footnotesize +\begin{verbatim} + RunAfterJob = "/home/kern/bacula/bin/watchdog %c %d" +\end{verbatim} +\normalsize + +which runs my "watchdog" script. As an example, I have added the Job codes +\%c and \%d which will cause the Client name and the Director's name to be +passed to the script. For example, if the Client's name is {\bf Watchdog} and +the Director's name is {\bf main-dir} then referencing \$1 in the script would +get {\bf Watchdog} and referencing \$2 would get {\bf main-dir}. In this case, +having the script know the Client and Director's name is not really useful, +but in other situations it may be. + +You can put anything in the watchdog script. In my case, I like to monitor the +size of my catalog to be sure that {\bf Bacula} is really pruning it. The +following is my watchdog script: + +\footnotesize +\begin{verbatim} +#!/bin/sh +cd /home/kern/mysql/var/bacula +du . * | +/home/kern/bacula/bin/bsmtp \ + -f "\(Bacula\) abuse@whitehouse.com" -h mail.yyyy.com \ + -s "Bacula running" abuse@whitehouse.com +\end{verbatim} +\normalsize + +If you just wish to send yourself a message, you can do it with: + +\footnotesize +\begin{verbatim} +#!/bin/sh +cd /home/kern/mysql/var/bacula +/home/kern/bacula/bin/bsmtp \ + -f "\(Bacula\) abuse@whitehouse.com" -h mail.yyyy.com \ + -s "Bacula running" abuse@whitehouse.com </volume-list + exit 0 +\end{verbatim} +\normalsize + +so that the whole case looks like: + +\footnotesize +\begin{verbatim} + list) +# +# commented out lines + cat /volume-list + exit 0 + ;; +\end{verbatim} +\normalsize + +where you replace \lt{}absolute-path\gt{} with the full path to the +volume-list file. Then using the console, you enter the following command: + +\footnotesize +\begin{verbatim} + label barcodes +\end{verbatim} +\normalsize + +and Bacula will proceed to mount the autochanger Volumes in the list and label +them with the Volume names you have supplied. Bacula will think that the list +was provided by the autochanger barcodes, but in reality, it was you who +supplied the \lt{}barcodes\gt{}. + +If it seems to work, when it finishes, enter: + +\footnotesize +\begin{verbatim} + list volumes +\end{verbatim} +\normalsize + +and you should see all the volumes nicely created. + +\section{Backing Up Portables Using DHCP} +\label{DNS} +\index[general]{DHCP!Backing Up Portables Using } +\index[general]{Backing Up Portables Using DHCP } + +You may want to backup laptops or portables that are not always connected to +the network. If you are using DHCP to assign an IP address to those machines +when they connect, you will need to use the Dynamic Update capability of DNS +to assign a name to those machines that can be used in the Address field of +the Client resource in the Director's conf file. + +\section{Going on Vacation} +\label{Vacation} +\index[general]{Vacation!Going on } +\index[general]{Going on Vacation } + +At some point, you may want to be absent for a week or two and you want to +make sure Bacula has enough tape left so that the backups will complete. You +start by doing a {\bf list volumes} in the Console program: + +\footnotesize +\begin{verbatim} +list volumes + +Using default Catalog name=BackupDB DB=bacula +Pool: Default ++---------+---------------+-----------+-----------+----------------+- +| MediaId | VolumeName | MediaType | VolStatus | VolBytes | ++---------+---------------+-----------+-----------+----------------+- +| 23 | DLT-30Nov02 | DLT8000 | Full | 54,739,278,128 | +| 24 | DLT-21Dec02 | DLT8000 | Full | 56,331,524,629 | +| 25 | DLT-11Jan03 | DLT8000 | Full | 67,863,514,895 | +| 26 | DLT-02Feb03 | DLT8000 | Full | 63,439,314,216 | +| 27 | DLT-03Mar03 | DLT8000 | Full | 66,022,754,598 | +| 28 | DLT-04Apr03 | DLT8000 | Full | 60,792,559,924 | +| 29 | DLT-28Apr03 | DLT8000 | Full | 62,072,494,063 | +| 30 | DLT-17May03 | DLT8000 | Full | 65,901,767,839 | +| 31 | DLT-07Jun03 | DLT8000 | Used | 56,558,490,015 | +| 32 | DLT-28Jun03 | DLT8000 | Full | 64,274,871,265 | +| 33 | DLT-19Jul03 | DLT8000 | Full | 64,648,749,480 | +| 34 | DLT-08Aug03 | DLT8000 | Full | 64,293,941,255 | +| 35 | DLT-24Aug03 | DLT8000 | Append | 9,999,216,782 | ++---------+---------------+-----------+-----------+----------------+ +\end{verbatim} +\normalsize + +Note, I have truncated the output for presentation purposes. What is +significant, is that I can see that my current tape has almost 10 Gbytes of +data, and that the average amount of data I get on my tapes is about 60 +Gbytes. So if I go on vacation now, I don't need to worry about tape capacity +(at least not for short absences). + +Equally significant is the fact that I did go on vacation the 28th of June +2003, and when I did the {\bf list volumes} command, my current tape at that +time, DLT-07Jun03 MediaId 31, had 56.5 Gbytes written. I could see that the +tape would fill shortly. Consequently, I manually marked it as {\bf Used} and +replaced it with a fresh tape that I labeled as DLT-28Jun03, thus assuring +myself that the backups would all complete without my intervention. + +\section{Exclude Files on Windows Regardless of Case} +\label{Case} +\index[general]{Exclude Files on Windows Regardless of Case} +% TODO: should this be put in the win32 chapter? +% TODO: should all these tips be placed in other chapters? + +This tip was submitted by Marc Brueckner who wasn't sure of the case of some +of his files on Win32, which is case insensitive. The problem is that Bacula +thinks that {\bf /UNIMPORTANT FILES} is different from {\bf /Unimportant +Files}. Marc was aware that the file exclusion permits wild-cards. So, he +specified: + +\footnotesize +\begin{verbatim} +"/[Uu][Nn][Ii][Mm][Pp][Oo][Rr][Tt][Aa][Nn][Tt] [Ff][Ii][Ll][Ee][Ss]" +\end{verbatim} +\normalsize + +As a consequence, the above exclude works for files of any case. + +Please note that this works only in Bacula Exclude statement and not in +Include. + +\section{Executing Scripts on a Remote Machine} +\label{RemoteExecution} +\index[general]{Machine!Executing Scripts on a Remote } +\index[general]{Executing Scripts on a Remote Machine } + +This tip also comes from Marc Brueckner. (Note, this tip is probably outdated +by the addition of {\bf ClientRunBeforJob} and {\bf ClientRunAfterJob} Job +records, but the technique still could be useful.) First I thought the "Run +Before Job" statement in the Job-resource is for executing a script on the +remote machine (the machine to be backed up). (Note, this is possible as mentioned +above by using {\bf ClientRunBeforJob} and {\bf ClientRunAfterJob}). +It could be useful to execute +scripts on the remote machine e.g. for stopping databases or other services +while doing the backup. (Of course I have to start the services again when the +backup has finished) I found the following solution: Bacula could execute +scripts on the remote machine by using ssh. The authentication is done +automatically using a private key. First you have to generate a keypair. I've +done this by: + +\footnotesize +\begin{verbatim} +ssh-keygen -b 4096 -t dsa -f Bacula_key +\end{verbatim} +\normalsize + +This statement may take a little time to run. It creates a public/private key +pair with no passphrase. You could save the keys in /etc/bacula. Now you have +two new files : Bacula\_key which contains the private key and Bacula\_key.pub +which contains the public key. + +Now you have to append the Bacula\_key.pub file to the file authorized\_keys +in the \textbackslash{}root\textbackslash{}.ssh directory of the remote +machine. Then you have to add (or uncomment) the line + +\footnotesize +\begin{verbatim} +AuthorizedKeysFile %h/.ssh/authorized_keys +\end{verbatim} +\normalsize + +to the sshd\_config file on the remote machine. Where the \%h stands for the +home-directory of the user (root in this case). + +Assuming that your sshd is already running on the remote machine, you can now +enter the following on the machine where Bacula runs: + +\footnotesize +\begin{verbatim} +ssh -i Bacula_key -l root "ls -la" +\end{verbatim} +\normalsize + +This should execute the "ls -la" command on the remote machine. + +Now you could add lines like the following to your Director's conf file: + +\footnotesize +\begin{verbatim} +... +Run Before Job = ssh -i /etc/bacula/Bacula_key 192.168.1.1 \ + "/etc/init.d/database stop" +Run After Job = ssh -i /etc/bacula/Bacula_key 192.168.1.1 \ + "/etc/init.d/database start" +... +\end{verbatim} +\normalsize + +Even though Bacula version 1.32 and later has a ClientRunBeforeJob, the ssh method still +could be useful for updating all the Bacula clients on several remote machines +in a single script. + +\section{Recycling All Your Volumes} +\label{recycle} +\index[general]{Recycling All Your Volumes } +\index[general]{Volumes!Recycling All Your } + +This tip comes from Phil Stracchino. + +If you decide to blow away your catalog and start over, the simplest way to +re-add all your prelabeled tapes with a minimum of fuss (provided you don't +care about the data on the tapes) is to add the tape labels using the console +{\bf add} command, then go into the catalog and manually set the VolStatus of +every tape to {\bf Recycle}. + +The SQL command to do this is very simple, either use your vendor's +command line interface (mysql, postgres, sqlite, ...) or use the sql +command in the Bacula console: + +\footnotesize +\begin{verbatim} +update Media set VolStatus='Recycle'; +\end{verbatim} +\normalsize + +Bacula will then ignore the data already stored on the tapes and just re-use +each tape without further objection. + +\section{Backing up ACLs on ext3 or XFS filesystems} +\label{ACLs} +\index[general]{Filesystems!Backing up ACLs on ext3 or XFS } +\index[general]{Backing up ACLs on ext3 or XFS filesystems } + +This tip comes from Volker Sauer. + +Note, this tip was given prior to implementation of ACLs in Bacula (version +1.34.5). It is left here because dumping/displaying ACLs can still be useful +in testing/verifying that Bacula is backing up and restoring your ACLs +properly. Please see the +\ilink{aclsupport}{ACLSupport} FileSet option in the +configuration chapter of this manual. + +For example, you could dump the ACLs to a file with a script similar to the +following: + +\footnotesize +\begin{verbatim} +#!/bin/sh +BACKUP_DIRS="/foo /bar" +STORE_ACL=/root/acl-backup +umask 077 +for i in $BACKUP_DIRS; do + cd $i /usr/bin/getfacl -R --skip-base .>$STORE_ACL/${i//\//_} +done +\end{verbatim} +\normalsize + +Then use Bacula to backup {\bf /root/acl-backup}. + +The ACLs could be restored using Bacula to the {\bf /root/acl-backup} file, +then restored to your system using: + +\footnotesize +\begin{verbatim} +setfacl --restore/root/acl-backup +\end{verbatim} +\normalsize + +\section{Total Automation of Bacula Tape Handling} +\label{automate} +\index[general]{Handling!Total Automation of Bacula Tape } +\index[general]{Total Automation of Bacula Tape Handling } + +This tip was provided by Alexander Kuehn. + +\elink{Bacula}{\url{http://www.bacula.org/}} is a really nice backup program except +that the manual tape changing requires user interaction with the bacula +console. + +Fortunately I can fix this. +NOTE!!! This suggestion applies for people who do *NOT* have tape autochangers +and must change tapes manually.!!!!! + +Bacula supports a variety of tape changers through the use of mtx-changer +scripts/programs. This highly flexible approach allowed me to create +\elink{this shell script}{\url{http://www.bacula.org/rel-manual/mtx-changer.txt}} which does the following: +% TODO: We need to include this in book appendix and point to it. +% TODO: +Whenever a new tape is required it sends a mail to the operator to insert the +new tape. Then it waits until a tape has been inserted, sends a mail again to +say thank you and let's bacula continue its backup. +So you can schedule and run backups without ever having to log on or see the +console. +To make the whole thing work you need to create a Device resource which looks +something like this ("Archive Device", "Maximum Changer Wait", "Media +Type" and "Label media" may have different values): + +\footnotesize +\begin{verbatim} +Device { + Name=DDS3 + Archive Device = # use yours not mine! ;)/dev/nsa0 + Changer Device = # not really required/dev/nsa0 + Changer Command = "# use this (maybe change the path)! + /usr/local/bin/mtx-changer %o %a %S" + Maximum Changer Wait = 3d # 3 days in seconds + AutomaticMount = yes; # mount on start + AlwaysOpen = yes; # keep device locked + Media Type = DDS3 # it's just a name + RemovableMedia = yes; # + Offline On Unmount = Yes; # keep this too + Label media = Yes; # +} +\end{verbatim} +\normalsize + +As the script has to emulate the complete wisdom of a mtx-changer it has an +internal "database" containing where which tape is stored, you can see this on +the following line: + +\footnotesize +\begin{verbatim} +labels="VOL-0001 VOL-0002 VOL-0003 VOL-0004 VOL-0005 VOL-0006 +VOL-0007 VOL-0008 VOL-0009 VOL-0010 VOL-0011 VOL-0012" +\end{verbatim} +\normalsize + +The above should be all on one line, and it effectively tells Bacula that +volume "VOL-0001" is located in slot 1 (which is our lowest slot), that +volume "VOL-0002" is located in slot 2 and so on.. +The script also maintains a logfile (/var/log/mtx.log) where you can monitor +its operation. + +\section{Running Concurrent Jobs} +\label{ConcurrentJobs} +\index[general]{Jobs!Running Concurrent} +\index[general]{Running Concurrent Jobs} +\index[general]{Concurrent Jobs} + +Bacula can run multiple concurrent jobs, but the default configuration files +do not enable it. Using the {\bf Maximum Concurrent Jobs} directive, you +can configure how many and which jobs can be run simultaneously. +The Director's default value for {\bf Maximum Concurrent Jobs} is "1". + +To initially setup concurrent jobs you need to define {\bf Maximum Concurrent Jobs} in +the Director's configuration file (bacula-dir.conf) in the +Director, Job, Client, and Storage resources. + +Additionally the File daemon, and the Storage daemon each have their own +{\bf Maximum Concurrent Jobs} directive that sets the overall maximum +number of concurrent jobs the daemon will run. The default for both the +File daemon and the Storage daemon is "20". + +For example, if you want two different jobs to run simultaneously backing up +the same Client to the same Storage device, they will run concurrently only if +you have set {\bf Maximum Concurrent Jobs} greater than one in the Director +resource, the Client resource, and the Storage resource in bacula-dir.conf. + +We recommend that you read the \ilink{Data +Spooling}{SpoolingChapter} of this manual first, then test your multiple +concurrent backup including restore testing before you put it into +production. + +Below is a super stripped down bacula-dir.conf file showing you the four +places where the the file must be modified to allow the same job {\bf +NightlySave} to run up to four times concurrently. The change to the Job +resource is not necessary if you want different Jobs to run at the same time, +which is the normal case. + +\footnotesize +\begin{verbatim} +# +# Bacula Director Configuration file -- bacula-dir.conf +# +Director { + Name = rufus-dir + Maximum Concurrent Jobs = 4 + ... +} +Job { + Name = "NightlySave" + Maximum Concurrent Jobs = 4 + Client = rufus-fd + Storage = File + ... +} +Client { + Name = rufus-fd + Maximum Concurrent Jobs = 4 + ... +} +Storage { + Name = File + Maximum Concurrent Jobs = 4 + ... +} +\end{verbatim} +\normalsize diff --git a/docs/manuals/fr/problems/translate_images.pl b/docs/manuals/fr/problems/translate_images.pl new file mode 100755 index 00000000..c7225118 --- /dev/null +++ b/docs/manuals/fr/problems/translate_images.pl @@ -0,0 +1,185 @@ +#!/usr/bin/perl -w +# +use strict; + +# Used to change the names of the image files generated by latex2html from imgxx.png +# to meaningful names. Provision is made to go either from or to the meaningful names. +# The meaningful names are obtained from a file called imagename_translations, which +# is generated by extensions to latex2html in the make_image_file subroutine in +# bacula.perl. + +# Opens the file imagename_translations and reads the contents into a hash. +# The hash is creaed with the imgxx.png files as the key if processing TO +# meaningful filenames, and with the meaningful filenames as the key if +# processing FROM meaningful filenames. +# Then opens the html file(s) indicated in the command-line arguments and +# changes all image references according to the translations described in the +# above file. Finally, it renames the image files. +# +# Original creation: 3-27-05 by Karl Cunningham. +# Modified 5-21-05 to go FROM and TO meaningful filenames. +# +my $TRANSFILE = "imagename_translations"; +my $path; + +# Loads the contents of $TRANSFILE file into the hash referenced in the first +# argument. The hash is loaded to translate old to new if $direction is 0, +# otherwise it is loaded to translate new to old. In this context, the +# 'old' filename is the meaningful name, and the 'new' filename is the +# imgxx.png filename. It is assumed that the old image is the one that +# latex2html has used as the source to create the imgxx.png filename. +# The filename extension is taken from the file +sub read_transfile { + my ($trans,$direction) = @_; + + if (!open IN,"<$path$TRANSFILE") { + print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n"; + print " Image filename translation aborted\n\n"; + exit 0; + } + + while () { + chomp; + my ($new,$old) = split(/\001/); + + # Old filenames will usually have a leading ./ which we don't need. + $old =~ s/^\.\///; + + # The filename extension of the old filename must be made to match + # the new filename because it indicates the encoding format of the image. + my ($ext) = $new =~ /(\.[^\.]*)$/; + $old =~ s/\.[^\.]*$/$ext/; + if ($direction == 0) { + $trans->{$new} = $old; + } else { + $trans->{$old} = $new; + } + } + close IN; +} + +# Translates the image names in the file given as the first argument, according to +# the translations in the hash that is given as the second argument. +# The file contents are read in entirely into a string, the string is processed, and +# the file contents are then written. No particular care is taken to ensure that the +# file is not lost if a system failure occurs at an inopportune time. It is assumed +# that the html files being processed here can be recreated on demand. +# +# Links to other files are added to the %filelist for processing. That way, +# all linked files will be processed (assuming they are local). +sub translate_html { + my ($filename,$trans,$filelist) = @_; + my ($contents,$out,$this,$img,$dest); + my $cnt = 0; + + # If the filename is an external link ignore it. And drop any file:// from + # the filename. + $filename =~ /^(http|ftp|mailto)\:/ and return 0; + $filename =~ s/^file\:\/\///; + # Load the contents of the html file. + if (!open IF,"<$path$filename") { + print "WARNING: Cannot open $path$filename for reading\n"; + print " Image Filename Translation aborted\n\n"; + exit 0; + } + + while () { + $contents .= $_; + } + close IF; + + # Now do the translation... + # First, search for an image filename. + while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) { + $contents = $'; + $out .= $` . $&; + + # The next thing is an image name. Get it and translate it. + $contents =~ /^(.*?)\"/s; + $contents = $'; + $this = $&; + $img = $1; + # If the image is in our list of ones to be translated, do it + # and feed the result to the output. + $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img})); + $out .= $this; + } + $out .= $contents; + + # Now send the translated text to the html file, overwriting what's there. + open OF,">$path$filename" or die "Cannot open $path$filename for writing\n"; + print OF $out; + close OF; + + # Now look for any links to other files and add them to the list of files to do. + while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) { + $out = $'; + $dest = $1; + # Drop an # and anything after it. + $dest =~ s/\#.*//; + $filelist->{$dest} = '' if $dest; + } + return $cnt; +} + +# REnames the image files spefified in the %translate hash. +sub rename_images { + my $translate = shift; + my ($response); + + foreach (keys(%$translate)) { + if (! $translate->{$_}) { + print " WARNING: No destination Filename for $_\n"; + } else { + $response = `mv -f $path$_ $path$translate->{$_} 2>&1`; + $response and print "ERROR from system $response\n"; + } + } +} + +################################################# +############# MAIN ############################# +################################################ + +# %filelist starts out with keys from the @ARGV list. As files are processed, +# any links to other files are added to the %filelist. A hash of processed +# files is kept so we don't do any twice. + +# The first argument must be either --to_meaningful_names or --from_meaningful_names + +my (%translate,$search_regex,%filelist,%completed,$thisfile); +my ($cnt,$direction); + +my $arg0 = shift(@ARGV); +$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or + die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n"; + +$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1; + +(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n"; + +# Use the first argument to get the path to the file of translations. +my $tmp = $ARGV[0]; +($path) = $tmp =~ /(.*\/)/; +$path = '' unless $path; + +read_transfile(\%translate,$direction); + +foreach (@ARGV) { + # Strip the path from the filename, and use it later on. + if (s/(.*\/)//) { + $path = $1; + } else { + $path = ''; + } + $filelist{$_} = ''; + + while ($thisfile = (keys(%filelist))[0]) { + $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile})); + delete($filelist{$thisfile}); + $completed{$thisfile} = ''; + } + print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n"; +} + +rename_images(\%translate); diff --git a/docs/manuals/fr/problems/update_version b/docs/manuals/fr/problems/update_version new file mode 100755 index 00000000..5c2e0092 --- /dev/null +++ b/docs/manuals/fr/problems/update_version @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/problems/update_version.in b/docs/manuals/fr/problems/update_version.in new file mode 100644 index 00000000..2766245f --- /dev/null +++ b/docs/manuals/fr/problems/update_version.in @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/problems/version.tex b/docs/manuals/fr/problems/version.tex new file mode 100644 index 00000000..82d910aa --- /dev/null +++ b/docs/manuals/fr/problems/version.tex @@ -0,0 +1 @@ +2.3.6 (04 November 2007) diff --git a/docs/manuals/fr/problems/version.tex.in b/docs/manuals/fr/problems/version.tex.in new file mode 100644 index 00000000..ff66dfc6 --- /dev/null +++ b/docs/manuals/fr/problems/version.tex.in @@ -0,0 +1 @@ +@VERSION@ (@DATE@) diff --git a/docs/manuals/fr/utility/Makefile b/docs/manuals/fr/utility/Makefile new file mode 100644 index 00000000..7136d1b6 --- /dev/null +++ b/docs/manuals/fr/utility/Makefile @@ -0,0 +1,135 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=utility + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Utility Programs" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Utilit*.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/utility/Makefile.in b/docs/manuals/fr/utility/Makefile.in new file mode 100644 index 00000000..7136d1b6 --- /dev/null +++ b/docs/manuals/fr/utility/Makefile.in @@ -0,0 +1,135 @@ +# +# +# Makefile for LaTeX +# +# To build everything do +# make tex +# make web +# make html +# make dvipdf +# +# or simply +# +# make +# +# for rapid development do: +# make tex +# make show +# +# +# If you are having problems getting "make" to work, debugging it is +# easier if can see the output from latex, which is normally redirected +# to /dev/null. To see it, do the following: +# +# cd docs/manual +# make tex +# latex bacula.tex +# +# typically the latex command will stop indicating the error (e.g. a +# missing \ in front of a _ or a missing { or ] ... +# +# The following characters must be preceded by a backslash +# to be entered as printable characters: +# +# # $ % & ~ _ ^ \ { } +# + +IMAGES=../../../images + +DOC=utility + +first_rule: all + +all: tex web dvipdf mini-clean + +.SUFFIXES: .tex .html +.PHONY: +.DONTCARE: + + +tex: + @./update_version + @echo "Making version `cat version.tex`" + @cp -fp ${IMAGES}/hires/*.eps . + @touch ${DOC}i-dir.tex ${DOC}i-fd.tex ${DOC}i-sd.tex \ + ${DOC}i-console.tex ${DOC}i-general.tex + latex -interaction=batchmode ${DOC}.tex + makeindex ${DOC}.idx -o ${DOC}.ind 2>/dev/null + latex -interaction=batchmode ${DOC}.tex + +pdf: + @echo "Making pdfm" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdfm -p a4 ${DOC}.dvi + +dvipdf: + @echo "Making dvi to pdf" + @cp -fp ${IMAGES}/hires/*.eps . + dvipdf ${DOC}.dvi ${DOC}.pdf + +html: + @echo " " + @echo "Making html" + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @(if [ -f imagename_translations ] ; then \ + ./translate_images.pl --from_meaningful_names ${DOC}.html; \ + fi) + latex2html -white -no_subdir -split 0 -toc_stars -white -notransparent \ + -init_file latex2html-init.pl ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}.html + @echo "Done making html" + +web: + @echo "Making web" + @mkdir -p ${DOC} + @cp -fp ${IMAGES}/*.eps . + @rm -f next.eps next.png prev.eps prev.png up.eps up.png + @cp -fp ${IMAGES}/*.eps ${DOC}/ + @cp -fp ${IMAGES}/*.eps ${IMAGES}/*.png ${DOC}/ + @rm -f ${DOC}/xp-*.png + @rm -f ${DOC}/next.eps ${DOC}/next.png ${DOC}/prev.eps ${DOC}/prev.png ${DOC}/up.eps ${DOC}/up.png + @rm -rf ${DOC}/*.html + latex2html -split 3 -local_icons -t "Bacula Utility Programs" -long_titles 4 \ + -toc_stars -contents_in_nav -init_file latex2html-init.pl -white -notransparent ${DOC} >tex.out 2>&1 + ./translate_images.pl --to_meaningful_names ${DOC}/Bacula_Utilit*.html + @echo "Done making web" +show: + xdvi ${DOC} + +texcheck: + ./check_tex.pl ${DOC}.tex + +main_configs: + pic2graph -density 100 main_configs.png + +mini-clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.gif *.jpg *.eps + @rm -f *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.backup *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd *.old *.out + @rm -f ${DOC}/*.gif ${DOC}/*.jpg ${DOC}/*.eps + @rm -f ${DOC}/*.aux ${DOC}/*.cp ${DOC}/*.fn ${DOC}/*.ky ${DOC}/*.log ${DOC}/*.pg + @rm -f ${DOC}/*.backup ${DOC}/*.ilg ${DOC}/*.lof ${DOC}/*.lot + @rm -f ${DOC}/*.cdx ${DOC}/*.cnd ${DOC}/*.ddx ${DOC}/*.ddn ${DOC}/*.fdx ${DOC}/*.fnd ${DOC}/*.ind ${DOC}/*.sdx ${DOC}/*.snd + @rm -f ${DOC}/*.dnd ${DOC}/*.old ${DOC}/*.out + @rm -f ${DOC}/WARNINGS + + +clean: + @rm -f 1 2 3 *.tex~ + @rm -f *.png *.gif *.jpg *.eps + @rm -f *.pdf *.aux *.cp *.fn *.ky *.log *.pg + @rm -f *.html *.backup *.ps *.dvi *.ilg *.lof *.lot + @rm -f *.cdx *.cnd *.ddx *.ddn *.fdx *.fnd *.ind *.sdx *.snd + @rm -f *.dnd imagename_translations + @rm -f *.old WARNINGS *.out *.toc *.idx + @rm -f ${DOC}i-*.tex + @rm -rf ${DOC} + + +distclean: clean + @rm -f images.pl labels.pl internals.pl + @rm -f Makefile version.tex diff --git a/docs/manuals/fr/utility/bimagemgr-chapter.tex b/docs/manuals/fr/utility/bimagemgr-chapter.tex new file mode 100644 index 00000000..01157f84 --- /dev/null +++ b/docs/manuals/fr/utility/bimagemgr-chapter.tex @@ -0,0 +1,155 @@ +%% +%% +%% The following characters must be preceded by a backslash +%% to be entered as printable characters: +%% +%% # $ % & ~ _ ^ \ { } +%% + +\section{bimagemgr} +\label{bimagemgr} +\index[general]{Bimagemgr } + +{\bf bimagemgr} is a utility for those who backup to disk volumes in order to +commit them to CDR disk, rather than tapes. It is a web based interface +written in Perl and is used to monitor when a volume file needs to be burned to +disk. It requires: + +\begin{itemize} +\item A web server running on the bacula server +\item A CD recorder installed and configured on the bacula server +\item The cdrtools package installed on the bacula server. +\item perl, perl-DBI module, and either DBD-MySQL DBD-SQLite or DBD-PostgreSQL modules + \end{itemize} + +DVD burning is not supported by {\bf bimagemgr} at this +time, but both are planned for future releases. + +\subsection{bimagemgr installation} +\index[general]{bimagemgr!Installation } +\index[general]{bimagemgr Installation } + +Installation from tarball: +% TODO: use itemized list for this? +1. Examine the Makefile and adjust it to your configuration if needed. +2. Edit config.pm to fit your configuration. +3. Do 'make install' as root. +4. Edit httpd.conf and change the Timeout value. The web server must not time +out and close the connection before the burn process is finished. The exact +value needed may vary depending upon your cd recorder speed and whether you are +burning on the bacula server on on another machine across your network. In my +case I set it to 1000 seconds. Restart httpd. +5. Make sure that cdrecord is setuid root. +% TODO: I am pretty sure cdrecord can be used without setuid root +% TODO: as long as devices are setup correctly + +Installation from rpm package: +% TODO: use itemized list for this? +1. Install the rpm package for your platform. +2. Edit /cgi-bin/config.pm to fit your configuration. +3. Edit httpd.conf and change the Timeout value. The web server must not time +out and close the connection before the burn process is finished. The exact +value needed may vary depending upon your cd recorder speed and whether you are +burning on the bacula server on on another machine across your network. In my +case I set it to 1000 seconds. Restart httpd. +4. Make sure that cdrecord is setuid root. + +For bacula systems less than 1.36: +% TODO: use itemized list for this? +1. Edit the configuration section of config.pm to fit your configuration. +2. Run /etc/bacula/create\_cdimage\_table.pl from a console on your bacula +server (as root) to add the CDImage table to your bacula database. + +Accessing the Volume files: +The Volume files by default have permissions 640 and can only be read by root. +The recommended approach to this is as follows (and only works if bimagemgr and +apache are running on the same host as bacula. + +For bacula-1.34 or 1.36 installed from tarball - +% TODO: use itemized list for this? +1. Create a new user group bacula and add the user apache to the group for +Red Hat or Mandrake systems. For SuSE systems add the user wwwrun to the +bacula group. +2. Change ownership of all of your Volume files to root.bacula +3. Edit the /etc/bacula/bacula startup script and set SD\_USER=root and +SD\_GROUP=bacula. Restart bacula. + +Note: step 3 should also be done in /etc/init.d/bacula-sd but released versions +of this file prior to 1.36 do not support it. In that case it would be necessary after +a reboot of the server to execute '/etc/bacula/bacula restart'. + +For bacula-1.38 installed from tarball - +% TODO: use itemized list for this? +1. Your configure statement should include: +% TODO: fix formatting here + --with-dir-user=bacula + --with-dir-group=bacula + --with-sd-user=bacula + --with-sd-group=disk + --with-fd-user=root + --with-fd-group=bacula +2. Add the user apache to the bacula group for Red Hat or Mandrake systems. +For SuSE systems add the user wwwrun to the bacula group. +3. Check/change ownership of all of your Volume files to root.bacula + +For bacula-1.36 or bacula-1.38 installed from rpm - +% TODO: use itemized list for this? +1. Add the user apache to the group bacula for Red Hat or Mandrake systems. +For SuSE systems add the user wwwrun to the bacula group. +2. Check/change ownership of all of your Volume files to root.bacula + +bimagemgr installed from rpm > 1.38.9 will add the web server user to the +bacula group in a post install script. Be sure to edit the configuration +information in config.pm after installation of rpm package. + +bimagemgr will now be able to read the Volume files but they are still not +world readable. + +If you are running bimagemgr on another host (not recommended) then you will +need to change the permissions on all of your backup volume files to 644 in +order to access them via nfs share or other means. This approach should only +be taken if you are sure of the security of your environment as it exposes +the backup Volume files to world read. + +\subsection{bimagemgr usage} +\index[general]{bimagemgr!Usage } +\index[general]{bimagemgr Usage } + +Calling the program in your web browser, e.g. {\tt +http://localhost/cgi-bin/bimagemgr.pl} will produce a display as shown below +% TODO: use tex to say figure number +in Figure 1. The program will query the bacula database and display all volume +files with the date last written and the date last burned to disk. If a volume +needs to be burned (last written is newer than last burn date) a "Burn" +button will be displayed in the rightmost column. + +\addcontentsline{lof}{figure}{Bacula CD Image Manager} +\includegraphics{./bimagemgr1.eps} \\Figure 1 +% TODO: use tex to say figure number + +Place a blank CDR disk in your recorder and click the "Burn" button. This will +cause a pop up window as shown in Figure 2 to display the burn progress. +% TODO: use tex to say figure number + +\addcontentsline{lof}{figure}{Bacula CD Image Burn Progress Window} +\includegraphics{./bimagemgr2.eps} \\Figure 2 +% TODO: use tex to say figure number + +When the burn finishes the pop up window will display the results of cdrecord +% TODO: use tex to say figure number +as shown in Figure 3. Close the pop up window and refresh the main window. The +last burn date will be updated and the "Burn" button for that volume will +disappear. Should you have a failed burn you can reset the last burn date of +that volume by clicking its "Reset" link. + +\addcontentsline{lof}{figure}{Bacula CD Image Burn Results} +\includegraphics{./bimagemgr3.eps} \\Figure 3 +% TODO: use tex to say figure number + +In the bottom row of the main display window are two more buttons labeled +"Burn Catalog" and "Blank CDRW". "Burn Catalog" will place a copy of +your bacula catalog on a disk. If you use CDRW disks rather than CDR then +"Blank CDRW" allows you to erase the disk before re-burning it. Regularly +committing your backup volume files and your catalog to disk with {\bf +bimagemgr} ensures that you can rebuild easily in the event of some disaster +on the bacula server itself. diff --git a/docs/manuals/fr/utility/check_tex.pl b/docs/manuals/fr/utility/check_tex.pl new file mode 100755 index 00000000..e12d51be --- /dev/null +++ b/docs/manuals/fr/utility/check_tex.pl @@ -0,0 +1,152 @@ +#!/usr/bin/perl -w +# Finds potential problems in tex files, and issues warnings to the console +# about what it finds. Takes a list of files as its only arguments, +# and does checks on all the files listed. The assumption is that these are +# valid (or close to valid) LaTeX files. It follows \include statements +# recursively to pick up any included tex files. +# +# +# +# Currently the following checks are made: +# +# -- Multiple hyphens not inside a verbatim environment (or \verb). These +# should be placed inside a \verb{} contruct so they will not be converted +# to single hyphen by latex and latex2html. + + +# Original creation 3-8-05 by Karl Cunningham karlc -at- keckec -dot- com +# +# + +use strict; + +# The following builds the test string to identify and change multiple +# hyphens in the tex files. Several constructs are identified but only +# multiple hyphens are changed; the others are fed to the output +# unchanged. +my $b = '\\\\begin\\*?\\s*\\{\\s*'; # \begin{ +my $e = '\\\\end\\*?\\s*\\{\\s*'; # \end{ +my $c = '\\s*\\}'; # closing curly brace + +# This captures entire verbatim environments. These are passed to the output +# file unchanged. +my $verbatimenv = $b . "verbatim" . $c . ".*?" . $e . "verbatim" . $c; + +# This captures \verb{..{ constructs. They are passed to the output unchanged. +my $verb = '\\\\verb\\*?(.).*?\\1'; + +# This captures multiple hyphens with a leading and trailing space. These are not changed. +my $hyphsp = '\\s\\-{2,}\\s'; + +# This identifies other multiple hyphens. +my $hyphens = '\\-{2,}'; + +# This identifies \hyperpage{..} commands, which should be ignored. +my $hyperpage = '\\\\hyperpage\\*?\\{.*?\\}'; + +# This builds the actual test string from the above strings. +#my $teststr = "$verbatimenv|$verb|$tocentry|$hyphens"; +my $teststr = "$verbatimenv|$verb|$hyphsp|$hyperpage|$hyphens"; + + +sub get_includes { + # Get a list of include files from the top-level tex file. The first + # argument is a pointer to the list of files found. The rest of the + # arguments is a list of filenames to check for includes. + my $files = shift; + my ($fileline,$includefile,$includes); + + while (my $filename = shift) { + # Get a list of all the html files in the directory. + open my $if,"<$filename" or die "Cannot open input file $filename\n"; + $fileline = 0; + $includes = 0; + while (<$if>) { + chomp; + $fileline++; + # If a file is found in an include, process it. + if (($includefile) = /\\include\s*\{(.*?)\}/) { + $includes++; + # Append .tex to the filename + $includefile .= '.tex'; + + # If the include file has already been processed, issue a warning + # and don't do it again. + my $found = 0; + foreach (@$files) { + if ($_ eq $includefile) { + $found = 1; + last; + } + } + if ($found) { + print "$includefile found at line $fileline in $filename was previously included\n"; + } else { + # The file has not been previously found. Save it and + # recursively process it. + push (@$files,$includefile); + get_includes($files,$includefile); + } + } + } + close IF; + } +} + + +sub check_hyphens { + my (@files) = @_; + my ($filedata,$this,$linecnt,$before); + + # Build the test string to check for the various environments. + # We only do the conversion if the multiple hyphens are outside of a + # verbatim environment (either \begin{verbatim}...\end{verbatim} or + # \verb{--}). Capture those environments and pass them to the output + # unchanged. + + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # Set up to process the file data. + $linecnt = 1; + + # Go through the file data from beginning to end. For each match, save what + # came before it and what matched. $filedata now becomes only what came + # after the match. + # Chech the match to see if it starts with a multiple-hyphen. If so + # warn the user. Keep track of line numbers so they can be output + # with the warning message. + while ($filedata =~ /$teststr/os) { + $this = $&; + $before = $`; + $filedata = $'; + $linecnt += $before =~ tr/\n/\n/; + + # Check if the multiple hyphen is present outside of one of the + # acceptable constructs. + if ($this =~ /^\-+/) { + print "Possible unwanted multiple hyphen found in line ", + "$linecnt of file $file\n"; + } + $linecnt += $this =~ tr/\n/\n/; + } + } +} +################################################################## +# MAIN #### +################################################################## + +my (@includes,$cnt); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +get_includes(\@includes,@ARGV); + +check_hyphens(@includes); diff --git a/docs/manuals/fr/utility/do_echo b/docs/manuals/fr/utility/do_echo new file mode 100644 index 00000000..04b9f79a --- /dev/null +++ b/docs/manuals/fr/utility/do_echo @@ -0,0 +1,6 @@ +# +# Avoid that @VERSION@ and @DATE@ are changed by configure +# This file is sourced by update_version +# +echo "s%@VERSION@%${VERSION}%g" >${out} +echo "s%@DATE@%${DATE}%g" >>${out} diff --git a/docs/manuals/fr/utility/fdl.tex b/docs/manuals/fr/utility/fdl.tex new file mode 100644 index 00000000..b46cd990 --- /dev/null +++ b/docs/manuals/fr/utility/fdl.tex @@ -0,0 +1,485 @@ +% TODO: maybe get rid of centering + +\chapter{GNU Free Documentation License} +\index[general]{GNU Free Documentation License} +\index[general]{License!GNU Free Documentation} + +\label{label_fdl} + + \begin{center} + + Version 1.2, November 2002 + + + Copyright \copyright 2000,2001,2002 Free Software Foundation, Inc. + + \bigskip + + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + \bigskip + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. +\end{center} + + +\begin{center} +{\bf\large Preamble} +\end{center} + +The purpose of this License is to make a manual, textbook, or other +functional and useful document "free" in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +\begin{center} +{\Large\bf 1. APPLICABILITY AND DEFINITIONS} +\end{center} + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The \textbf{"Document"}, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as \textbf{"you"}. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A \textbf{"Modified Version"} of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A \textbf{"Secondary Section"} is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The \textbf{"Invariant Sections"} are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The \textbf{"Cover Texts"} are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A \textbf{"Transparent"} copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not "Transparent" is called \textbf{"Opaque"}. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The \textbf{"Title Page"} means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section \textbf{"Entitled XYZ"} means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as \textbf{"Acknowledgements"}, +\textbf{"Dedications"}, \textbf{"Endorsements"}, or \textbf{"History"}.) +To \textbf{"Preserve the Title"} +of such a section when you modify the Document means that it remains a +section "Entitled XYZ" according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + + +\begin{center} +{\Large\bf 2. VERBATIM COPYING} +\end{center} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\begin{center} +{\Large\bf 3. COPYING IN QUANTITY} +\end{center} + + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\begin{center} +{\Large\bf 4. MODIFICATIONS} +\end{center} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} +\item[A.] + Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. + +\item[B.] + List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement. + +\item[C.] + State on the Title page the name of the publisher of the + Modified Version, as the publisher. + +\item[D.] + Preserve all the copyright notices of the Document. + +\item[E.] + Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + +\item[F.] + Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. + +\item[G.] + Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. + +\item[H.] + Include an unaltered copy of this License. + +\item[I.] + Preserve the section Entitled "History", Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + +\item[J.] + Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + +\item[K.] + For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein. + +\item[L.] + Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. + +\item[M.] + Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + +\item[N.] + Do not retitle any existing section to be Entitled "Endorsements" + or to conflict in title with any Invariant Section. + +\item[O.] + Preserve any Warranty Disclaimers. +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\begin{center} +{\Large\bf 5. COMBINING DOCUMENTS} +\end{center} + + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled "History" +in the various original documents, forming one section Entitled +"History"; likewise combine any sections Entitled "Acknowledgements", +and any sections Entitled "Dedications". You must delete all sections +Entitled "Endorsements". + +\begin{center} +{\Large\bf 6. COLLECTIONS OF DOCUMENTS} +\end{center} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +\begin{center} +{\Large\bf 7. AGGREGATION WITH INDEPENDENT WORKS} +\end{center} + + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an "aggregate" if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + + +\begin{center} +{\Large\bf 8. TRANSLATION} +\end{center} + + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + + +\begin{center} +{\Large\bf 9. TERMINATION} +\end{center} + + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\begin{center} +{\Large\bf 10. FUTURE REVISIONS OF THIS LICENSE} +\end{center} + + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +\begin{center} +{\Large\bf ADDENDUM: How to use this License for your documents} +% TODO: this is too long for table of contents +\end{center} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\bigskip +\begin{quote} + Copyright \copyright YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +\end{quote} +\bigskip + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with...Texts." line with this: + +\bigskip +\begin{quote} + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. +\end{quote} +\bigskip + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +%--------------------------------------------------------------------- diff --git a/docs/manuals/fr/utility/fix_tex.pl b/docs/manuals/fr/utility/fix_tex.pl new file mode 100755 index 00000000..98657576 --- /dev/null +++ b/docs/manuals/fr/utility/fix_tex.pl @@ -0,0 +1,184 @@ +#!/usr/bin/perl -w +# Fixes various things within tex files. + +use strict; + +my %args; + + +sub get_includes { + # Get a list of include files from the top-level tex file. + my (@list,$file); + + foreach my $filename (@_) { + $filename or next; + # Start with the top-level latex file so it gets checked too. + push (@list,$filename); + + # Get a list of all the html files in the directory. + open IF,"<$filename" or die "Cannot open input file $filename"; + while () { + chomp; + push @list,"$1.tex" if (/\\include\{(.*?)\}/); + } + + close IF; + } + return @list; +} + +sub convert_files { + my (@files) = @_; + my ($linecnt,$filedata,$output,$itemcnt,$indentcnt,$cnt); + + $cnt = 0; + foreach my $file (@files) { + # Open the file and load the whole thing into $filedata. A bit wasteful but + # easier to deal with, and we don't have a problem with speed here. + $filedata = ""; + open IF,"<$file" or die "Cannot open input file $file"; + while () { + $filedata .= $_; + } + close IF; + + # We look for a line that starts with \item, and indent the two next lines (if not blank) + # by three spaces. + my $linecnt = 3; + $indentcnt = 0; + $output = ""; + # Process a line at a time. + foreach (split(/\n/,$filedata)) { + $_ .= "\n"; # Put back the return. + # If this line is less than the third line past the \item command, + # and the line isn't blank and doesn't start with whitespace + # add three spaces to the start of the line. Keep track of the number + # of lines changed. + if ($linecnt < 3 and !/^\\item/) { + if (/^[^\n\s]/) { + $output .= " " . $_; + $indentcnt++; + } else { + $output .= $_; + } + $linecnt++; + } else { + $linecnt = 3; + $output .= $_; + } + /^\\item / and $linecnt = 1; + } + + + # This is an item line. We need to process it too. If inside a \begin{description} environment, convert + # \item {\bf xxx} to \item [xxx] or \item [{xxx}] (if xxx contains '[' or ']'. + $itemcnt = 0; + $filedata = $output; + $output = ""; + my ($before,$descrip,$this,$between); + + # Find any \begin{description} environment + while ($filedata =~ /(\\begin[\s\n]*\{[\s\n]*description[\s\n]*\})(.*?)(\\end[\s\n]*\{[\s\n]*description[\s\n]*\})/s) { + $output .= $` . $1; + $filedata = $3 . $'; + $descrip = $2; + + # Search for \item {\bf xxx} + while ($descrip =~ /\\item[\s\n]*\{[\s\n]*\\bf[\s\n]*/s) { + $descrip = $'; + $output .= $`; + ($between,$descrip) = find_matching_brace($descrip); + if (!$descrip) { + $linecnt = $output =~ tr/\n/\n/; + print STDERR "Missing matching curly brace at line $linecnt in $file\n" if (!$descrip); + } + + # Now do the replacement. + $between = '{' . $between . '}' if ($between =~ /\[|\]/); + $output .= "\\item \[$between\]"; + $itemcnt++; + } + $output .= $descrip; + } + $output .= $filedata; + + # If any hyphens or \item commnads were converted, save the file. + if ($indentcnt or $itemcnt) { + open OF,">$file" or die "Cannot open output file $file"; + print OF $output; + close OF; + print "$indentcnt indent", ($indentcnt == 1) ? "" : "s"," added in $file\n"; + print "$itemcnt item", ($itemcnt == 1) ? "" : "s"," Changed in $file\n"; + } + + $cnt += $indentcnt + $itemcnt; + } + return $cnt; +} + +sub find_matching_brace { + # Finds text up to the next matching brace. Assumes that the input text doesn't contain + # the opening brace, but we want to find text up to a matching closing one. + # Returns the text between the matching braces, followed by the rest of the text following + # (which does not include the matching brace). + # + my $str = shift; + my ($this,$temp); + my $cnt = 1; + + while ($cnt) { + # Ignore verbatim constructs involving curly braces, or if the character preceding + # the curly brace is a backslash. + if ($str =~ /\\verb\*?\{.*?\{|\\verb\*?\}.*?\}|\{|\}/s) { + $this .= $`; + $str = $'; + $temp = $&; + + if ((substr($this,-1,1) eq '\\') or + $temp =~ /^\\verb/) { + $this .= $temp; + next; + } + + $cnt += ($temp eq '{') ? 1 : -1; + # If this isn't the matching curly brace ($cnt > 0), include the brace. + $this .= $temp if ($cnt); + } else { + # No matching curly brace found. + return ($this . $str,''); + } + } + return ($this,$str); +} + +sub check_arguments { + # Checks command-line arguments for ones starting with -- puts them into + # a hash called %args and removes them from @ARGV. + my $args = shift; + my $i; + + for ($i = 0; $i < $#ARGV; $i++) { + $ARGV[$i] =~ /^\-+/ or next; + $ARGV[$i] =~ s/^\-+//; + $args{$ARGV[$i]} = ""; + delete ($ARGV[$i]); + + } +} + +################################################################## +# MAIN #### +################################################################## + +my @includes; +my $cnt; + +check_arguments(\%args); +die "No Files given to Check\n" if ($#ARGV < 0); + +# Examine the file pointed to by the first argument to get a list of +# includes to test. +@includes = get_includes(@ARGV); + +$cnt = convert_files(@includes); +print "No lines changed\n" unless $cnt; diff --git a/docs/manuals/fr/utility/index.perl b/docs/manuals/fr/utility/index.perl new file mode 100644 index 00000000..bc4e1b60 --- /dev/null +++ b/docs/manuals/fr/utility/index.perl @@ -0,0 +1,564 @@ +# This module does multiple indices, supporting the style of the LaTex 'index' +# package. + +# Version Information: +# 16-Feb-2005 -- Original Creation. Karl E. Cunningham +# 14-Mar-2005 -- Clarified and Consolodated some of the code. +# Changed to smoothly handle single and multiple indices. + +# Two LaTeX index formats are supported... +# --- SINGLE INDEX --- +# \usepackage{makeidx} +# \makeindex +# \index{entry1} +# \index{entry2} +# \index{entry3} +# ... +# \printindex +# +# --- MULTIPLE INDICES --- +# +# \usepackage{makeidx} +# \usepackage{index} +# \makeindex -- latex2html doesn't care but LaTeX does. +# \newindex{ref1}{ext1}{ext2}{title1} +# \newindex{ref2}{ext1}{ext2}{title2} +# \newindex{ref3}{ext1}{ext2}{title3} +# \index[ref1]{entry1} +# \index[ref1]{entry2} +# \index[ref3]{entry3} +# \index[ref2]{entry4} +# \index{entry5} +# \index[ref3]{entry6} +# ... +# \printindex[ref1] +# \printindex[ref2] +# \printindex[ref3] +# \printindex +# ___________________ +# +# For the multiple-index style, each index is identified by the ref argument to \newindex, \index, +# and \printindex. A default index is allowed, which is indicated by omitting the optional +# argument. The default index does not require a \newindex command. As \index commands +# are encountered, their entries are stored according +# to the ref argument. When the \printindex command is encountered, the stored index +# entries for that argument are retrieved and printed. The title for each index is taken +# from the last argument in the \newindex command. +# While processing \index and \printindex commands, if no argument is given the index entries +# are built into a default index. The title of the default index is simply "Index". +# This makes the difference between single- and multiple-index processing trivial. +# +# Another method can be used by omitting the \printindex command and just using \include to +# pull in index files created by the makeindex program. These files will start with +# \begin{theindex}. This command is used to determine where to print the index. Using this +# approach, the indices will be output in the same order as the newindex commands were +# originally found (see below). Using a combination of \printindex and \include{indexfile} has not +# been tested and may produce undesireable results. +# +# The index data are stored in a hash for later sorting and output. As \printindex +# commands are handled, the order in which they were found in the tex filea is saved, +# associated with the ref argument to \printindex. +# +# We use the original %index hash to store the index data into. We append a \002 followed by the +# name of the index to isolate the entries in different indices from each other. This is necessary +# so that different indices can have entries with the same name. For the default index, the \002 is +# appended without the name. +# +# Since the index order in the output cannot be determined if the \include{indexfile} +# command is used, the order will be assumed from the order in which the \newindex +# commands were originally seen in the TeX files. This order is saved as well as the +# order determined from any printindex{ref} commands. If \printindex commnads are used +# to specify the index output, that order will be used. If the \include{idxfile} command +# is used, the order of the original newindex commands will be used. In this case the +# default index will be printed last since it doesn't have a corresponding \newindex +# command and its order cannot be determined. Mixing \printindex and \include{idxfile} +# commands in the same file is likely to produce less than satisfactory results. +# +# +# The hash containing index data is named %indices. It contains the following data: +#{ +# 'title' => { +# $ref1 => $indextitle , +# $ref2 => $indextitle , +# ... +# }, +# 'newcmdorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +# 'printindorder' => [ ref1, ref2, ..., * ], # asterisk indicates the position of the default index. +#} + + +# Globals to handle multiple indices. +my %indices; + +# This tells the system to use up to 7 words in index entries. +$WORDS_IN_INDEX = 10; + +# KEC 2-18-05 +# Handles the \newindex command. This is called if the \newindex command is +# encountered in the LaTex source. Gets the index ref and title from the arguments. +# Saves the index ref and title. +# Note that we are called once to handle multiple \newindex commands that are +# newline-separated. +sub do_cmd_newindex { + my $data = shift; + # The data is sent to us as fields delimited by their ID #'s. We extract the + # fields. + foreach my $line (split("\n",$data)) { + my @fields = split (/(?:\<\#\d+?\#\>)+/,$line); + + # The index name and title are the second and fourth fields in the data. + if ($line =~ /^ \001 + # @ -> \002 + # | -> \003 + $* = 1; $str =~ s/\n\s*/ /g; $* = 0; # remove any newlines + # protect \001 occurring with images + $str =~ s/\001/\016/g; # 0x1 to 0xF + $str =~ s/\\\\/\011/g; # Double backslash -> 0xB + $str =~ s/\\;SPMquot;/\012/g; # \;SPMquot; -> 0xC + $str =~ s/;SPMquot;!/\013/g; # ;SPMquot; -> 0xD + $str =~ s/!/\001/g; # Exclamation point -> 0x1 + $str =~ s/\013/!/g; # 0xD -> Exclaimation point + $str =~ s/;SPMquot;@/\015/g; # ;SPMquot;@ to 0xF + $str =~ s/@/\002/g; # At sign -> 0x2 + $str =~ s/\015/@/g; # 0xF to At sign + $str =~ s/;SPMquot;\|/\017/g; # ;SMPquot;| to 0x11 + $str =~ s/\|/\003/g; # Vertical line to 0x3 + $str =~ s/\017/|/g; # 0x11 to vertical line + $str =~ s/;SPMquot;(.)/\1/g; # ;SPMquot; -> whatever the next character is + $str =~ s/\012/;SPMquot;/g; # 0x12 to ;SPMquot; + $str =~ s/\011/\\\\/g; # 0x11 to double backslash + local($key_part, $pageref) = split("\003", $str, 2); + + # For any keys of the form: blablabla!blablabla, which want to be split at the + # exclamation point, replace the ! with a comma and a space. We don't do it + # that way for this index. + $key_part =~ s/\001/, /g; + local(@keys) = split("\001", $key_part); + # If TITLE is not yet available use $before. + $TITLE = $saved_title if (($saved_title)&&(!($TITLE)||($TITLE eq $default_title))); + $TITLE = $before unless $TITLE; + # Save the reference + local($words) = ''; + if ($SHOW_SECTION_NUMBERS) { $words = &make_idxnum; } + elsif ($SHORT_INDEX) { $words = &make_shortidxname; } + else { $words = &make_idxname; } + local($super_key) = ''; + local($sort_key, $printable_key, $cur_key); + foreach $key (@keys) { + $key =~ s/\016/\001/g; # revert protected \001s + ($sort_key, $printable_key) = split("\002", $key); + # + # RRM: 16 May 1996 + # any \label in the printable-key will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($printable_key =~ /tex2html_anchor_mark/ ) { + $printable_key =~ s/><\/A>$cross_ref_mark/ + $printable_key =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_label = $external_labels{$label} unless + ($ref_label = $ref_files{$label}); + '"' . "$ref_label#$label" . '">' . + &get_ref_mark($label,$id)} + /geo; + } + $printable_key =~ s/<\#[^\#>]*\#>//go; + #RRM + # recognise \char combinations, for a \backslash + # + $printable_key =~ s/\&\#;\'134/\\/g; # restore \\s + $printable_key =~ s/\&\#;\`
/\\/g; # ditto + $printable_key =~ s/\&\#;*SPMquot;92/\\/g; # ditto + # + # $sort_key .= "@$printable_key" if !($printable_key); # RRM + $sort_key .= "@$printable_key" if !($sort_key); # RRM + $sort_key =~ tr/A-Z/a-z/; + if ($super_key) { + $cur_key = $super_key . "\001" . $sort_key; + $sub_index{$super_key} .= $cur_key . "\004"; + } else { + $cur_key = $sort_key; + } + + # Append the $index_name to the current key with a \002 delimiter. This will + # allow the same index entry to appear in more than one index. + $index_key = $cur_key . "\002$index_name"; + + $index{$index_key} .= ""; + + # + # RRM, 15 June 1996 + # if there is no printable key, but one is known from + # a previous index-entry, then use it. + # + if (!($printable_key) && ($printable_key{$index_key})) + { $printable_key = $printable_key{$index_key}; } +# if (!($printable_key) && ($printable_key{$cur_key})) +# { $printable_key = $printable_key{$cur_key}; } + # + # do not overwrite the printable_key if it contains an anchor + # + if (!($printable_key{$index_key} =~ /tex2html_anchor_mark/ )) + { $printable_key{$index_key} = $printable_key || $key; } +# if (!($printable_key{$cur_key} =~ /tex2html_anchor_mark/ )) +# { $printable_key{$cur_key} = $printable_key || $key; } + + $super_key = $cur_key; + } + # + # RRM + # page-ranges, from |( and |) and |see + # + if ($pageref) { + if ($pageref eq "\(" ) { + $pageref = ''; + $next .= " from "; + } elsif ($pageref eq "\)" ) { + $pageref = ''; + local($next) = $index{$index_key}; +# local($next) = $index{$cur_key}; + # $next =~ s/[\|] *$//; + $next =~ s/(\n )?\| $//; + $index{$index_key} = "$next to "; +# $index{$cur_key} = "$next to "; + } + } + + if ($pageref) { + $pageref =~ s/\s*$//g; # remove trailing spaces + if (!$pageref) { $pageref = ' ' } + $pageref =~ s/see/see <\/i> /g; + # + # RRM: 27 Dec 1996 + # check if $pageref corresponds to a style command. + # If so, apply it to the $words. + # + local($tmp) = "do_cmd_$pageref"; + if (defined &$tmp) { + $words = &$tmp("<#0#>$words<#0#>"); + $words =~ s/<\#[^\#]*\#>//go; + $pageref = ''; + } + } + # + # RRM: 25 May 1996 + # any \label in the pageref section will have already + # created a label where the \index occurred. + # This has to be removed, so that the desired label + # will be found on the Index page instead. + # + if ($pageref) { + if ($pageref =~ /tex2html_anchor_mark/ ) { + $pageref =~ s/><\/A>$cross_ref_mark/ + $pageref =~ s/$cross_ref_mark#([^#]+)#([^>]+)>$cross_ref_mark/ + do { ($label,$id) = ($1,$2); + $ref_files{$label} = ''; # ???? RRM + if ($index_labels{$label}) { $ref_label = ''; } + else { $ref_label = $external_labels{$label} + unless ($ref_label = $ref_files{$label}); + } + '"' . "$ref_label#$label" . '">' . &get_ref_mark($label,$id)}/geo; + } + $pageref =~ s/<\#[^\#>]*\#>//go; + + if ($pageref eq ' ') { $index{$index_key}='@'; } + else { $index{$index_key} .= $pageref . "\n | "; } + } else { + local($thisref) = &make_named_href('',"$CURRENT_FILE#$br_id",$words); + $thisref =~ s/\n//g; + $index{$index_key} .= $thisref."\n | "; + } + #print "\nREF: $sort_key : $index_key :$index{$index_key}"; + + #join('',"$anchor_invisible_mark<\/A>",$_); + + "$anchor_invisible_mark<\/A>"; +} + + +# KEC. -- Copied from makeidx.perl, then modified to do multiple indices. +# Feeds the index entries to the output. This is called for each index to be built. +# +# Generates a list of lookup keys for index entries, from both %printable_keys +# and %index keys. +# Sorts the keys according to index-sorting rules. +# Removes keys with a 0x01 token. (duplicates?) +# Builds a string to go to the index file. +# Adds the index entries to the string if they belong in this index. +# Keeps track of which index is being worked on, so only the proper entries +# are included. +# Places the index just built in to the output at the proper place. +{ my $index_number = 0; +sub add_real_idx { + print "\nDoing the index ... Index Number $index_number\n"; + local($key, @keys, $next, $index, $old_key, $old_html); + my ($idx_ref,$keyref); + # RRM, 15.6.96: index constructed from %printable_key, not %index + @keys = keys %printable_key; + + while (/$idx_mark/) { + # Get the index reference from what follows the $idx_mark and + # remove it from the string. + s/$idxmark\002(.*?)\002/$idxmark/; + $idx_ref = $1; + $index = ''; + # include non- makeidx index-entries + foreach $key (keys %index) { + next if $printable_key{$key}; + $old_key = $key; + if ($key =~ s/###(.*)$//) { + next if $printable_key{$key}; + push (@keys, $key); + $printable_key{$key} = $key; + if ($index{$old_key} =~ /HREF="([^"]*)"/i) { + $old_html = $1; + $old_html =~ /$dd?([^#\Q$dd\E]*)#/; + $old_html = $1; + } else { $old_html = '' } + $index{$key} = $index{$old_key} . $old_html."\n | "; + }; + } + @keys = sort makeidx_keysort @keys; + @keys = grep(!/\001/, @keys); + my $cnt = 0; + foreach $key (@keys) { + my ($keyref) = $key =~ /.*\002(.*)/; + next unless ($idx_ref eq $keyref); # KEC. + $index .= &add_idx_key($key); + $cnt++; + } + print "$cnt Index Entries Added\n"; + $index = '
'.$index unless ($index =~ /^\s*/); + $index_number++; # KEC. + if ($SHORT_INDEX) { + print "(compact version with Legend)"; + local($num) = ( $index =~ s/\ 50 ) { + s/$idx_mark/$preindex
\n$index\n<\/DL>$preindex/o; + } else { + s/$idx_mark/$preindex
\n$index\n<\/DL>/o; + } + } else { + s/$idx_mark/
\n$index\n<\/DL>/o; } + } +} +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# The bibliography and the index should be treated as separate sections +# in their own HTML files. The \bibliography{} command acts as a sectioning command +# that has the desired effect. But when the bibliography is constructed +# manually using the thebibliography environment, or when using the +# theindex environment it is not possible to use the normal sectioning +# mechanism. This subroutine inserts a \bibliography{} or a dummy +# \textohtmlindex command just before the appropriate environments +# to force sectioning. +sub add_bbl_and_idx_dummy_commands { + local($id) = $global{'max_id'}; + + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$bbl_cnt++; $1/eg; + ## if ($bbl_cnt == 1) { + s/([\\]begin\s*$O\d+$C\s*thebibliography)/$id++; "\\bibliography$O$id$C$O$id$C $1"/geo; + #} + $global{'max_id'} = $id; + # KEC. Modified to global substitution to place multiple index tokens. + s/[\\]begin\s*($O\d+$C)\s*theindex/\\textohtmlindex$1/go; + # KEC. Modified to pick up the optional argument to \printindex + s/[\\]printindex\s*(\[.*?\])?/ + do { (defined $1) ? "\\textohtmlindex $1" : "\\textohtmlindex []"; } /ego; + &lib_add_bbl_and_idx_dummy_commands() if defined(&lib_add_bbl_and_idx_dummy_commands); +} + +# KEC. Copied from latex2html.pl and modified to support multiple indices. +# For each textohtmlindex mark found, determine the index titles and headers. +# We place the index ref in the header so the proper index can be generated later. +# For the default index, the index ref is blank. +# +# One problem is that this routine is called twice.. Once for processing the +# command as originally seen, and once for processing the command when +# doing the name for the index file. We can detect that by looking at the +# id numbers (or ref) surrounding the \theindex command, and not incrementing +# index_number unless a new id (or ref) is seen. This has the side effect of +# having to unconventionally start the index_number at -1. But it works. +# +# Gets the title from the list of indices. +# If this is the first index, save the title in $first_idx_file. This is what's referenced +# in the navigation buttons. +# Increment the index_number for next time. +# If the indexname command is defined or a newcommand defined for indexname, do it. +# Save the index TITLE in the toc +# Save the first_idx_file into the idxfile. This goes into the nav buttons. +# Build index_labels if needed. +# Create the index headings and put them in the output stream. + +{ my $index_number = 0; # Will be incremented before use. + my $first_idx_file; # Static + my $no_increment = 0; + +sub do_cmd_textohtmlindex { + local($_) = @_; + my ($idxref,$idxnum,$index_name); + + # We get called from make_name with the first argument = "\001noincrement". This is a sign + # to not increment $index_number the next time we are called. We get called twice, once + # my make_name and once by process_command. Unfortunately, make_name calls us just to set the name + # but doesn't use the result so we get called a second time by process_command. This works fine + # except for cases where there are multiple indices except if they aren't named, which is the case + # when the index is inserted by an include command in latex. In these cases we are only able to use + # the index number to decide which index to draw from, and we don't know how to increment that index + # number if we get called a variable number of times for the same index, as is the case between + # making html (one output file) and web (multiple output files) output formats. + if (/\001noincrement/) { + $no_increment = 1; + return; + } + + # Remove (but save) the index reference + s/^\s*\[(.*?)\]/{$idxref = $1; "";}/e; + + # If we have an $idxref, the index name was specified. In this case, we have all the + # information we need to carry on. Otherwise, we need to get the idxref + # from the $index_number and set the name to "Index". + if ($idxref) { + $index_name = $indices{'title'}{$idxref}; + } else { + if (defined ($idxref = $indices{'newcmdorder'}->[$index_number])) { + $index_name = $indices{'title'}{$idxref}; + } else { + $idxref = ''; + $index_name = "Index"; + } + } + + $idx_title = "Index"; # The name displayed in the nav bar text. + + # Only set $idxfile if we are at the first index. This will point the + # navigation panel to the first index file rather than the last. + $first_idx_file = $CURRENT_FILE if ($index_number == 0); + $idxfile = $first_idx_file; # Pointer for the Index button in the nav bar. + $toc_sec_title = $index_name; # Index link text in the toc. + $TITLE = $toc_sec_title; # Title for this index, from which its filename is built. + if (%index_labels) { &make_index_labels(); } + if (($SHORT_INDEX) && (%index_segment)) { &make_preindex(); } + else { $preindex = ''; } + local $idx_head = $section_headings{'textohtmlindex'}; + local($heading) = join('' + , &make_section_heading($TITLE, $idx_head) + , $idx_mark, "\002", $idxref, "\002" ); + local($pre,$post) = &minimize_open_tags($heading); + $index_number++ unless ($no_increment); + $no_increment = 0; + join('',"
\n" , $pre, $_); +} +} + +# Returns an index key, given the key passed as the first argument. +# Not modified for multiple indices. +sub add_idx_key { + local($key) = @_; + local($index, $next); + if (($index{$key} eq '@' )&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { $index .= "

\n
".&print_key."\n
"; } + else { $index .= "

\n
".&print_key."\n
"; } + } elsif (($index{$key})&&(!($index_printed{$key}))) { + if ($SHORT_INDEX) { + $next = "
".&print_key."\n : ". &print_idx_links; + } else { + $next = "
".&print_key."\n
". &print_idx_links; + } + $index .= $next."\n"; + $index_printed{$key} = 1; + } + + if ($sub_index{$key}) { + local($subkey, @subkeys, $subnext, $subindex); + @subkeys = sort(split("\004", $sub_index{$key})); + if ($SHORT_INDEX) { + $index .= "
".&print_key unless $index_printed{$key}; + $index .= "
\n"; + } else { + $index .= "
".&print_key."\n
" unless $index_printed{$key}; + $index .= "
\n"; + } + foreach $subkey (@subkeys) { + $index .= &add_sub_idx_key($subkey) unless ($index_printed{$subkey}); + } + $index .= "
\n"; + } + return $index; +} + +1; # Must be present as the last line. diff --git a/docs/manuals/fr/utility/latex2html-init.pl b/docs/manuals/fr/utility/latex2html-init.pl new file mode 100644 index 00000000..14b5c319 --- /dev/null +++ b/docs/manuals/fr/utility/latex2html-init.pl @@ -0,0 +1,10 @@ +# This file serves as a place to put initialization code and constants to +# affect the behavior of latex2html for generating the bacula manuals. + +# $LINKPOINT specifies what filename to use to link to when creating +# index.html. Not that this is a hard link. +$LINKPOINT='"$OVERALL_TITLE"'; + + +# The following must be the last line of this file. +1; diff --git a/docs/manuals/fr/utility/progs.tex b/docs/manuals/fr/utility/progs.tex new file mode 100644 index 00000000..9187970d --- /dev/null +++ b/docs/manuals/fr/utility/progs.tex @@ -0,0 +1,1332 @@ +%% +%% + +\chapter{Volume Utility Tools} +\label{_UtilityChapter} +\index[general]{Volume Utility Tools} +\index[general]{Tools!Volume Utility} + +This document describes the utility programs written to aid Bacula users and +developers in dealing with Volumes external to Bacula. + +\section{Specifying the Configuration File} +\index[general]{Specifying the Configuration File} + +Starting with version 1.27, each of the following programs requires a valid +Storage daemon configuration file (actually, the only part of the +configuration file that these programs need is the {\bf Device} resource +definitions). This permits the programs to find the configuration parameters +for your archive device (generally a tape drive). By default, they read {\bf +bacula-sd.conf} in the current directory, but you may specify a different +configuration file using the {\bf -c} option. + + +\section{Specifying a Device Name For a Tape} +\index[general]{Tape!Specifying a Device Name For a} +\index[general]{Specifying a Device Name For a Tape} + +Each of these programs require a {\bf device-name} where the Volume can be +found. In the case of a tape, this is the physical device name such as {\bf +/dev/nst0} or {\bf /dev/rmt/0ubn} depending on your system. For the program to +work, it must find the identical name in the Device resource of the +configuration file. See below for specifying Volume names. + +Please note that if you have Bacula running and you ant to use +one of these programs, you will either need to stop the Storage daemon, or +{\bf unmount} any tape drive you want to use, otherwise the drive +will {\bf busy} because Bacula is using it. + + +\section{Specifying a Device Name For a File} +\index[general]{File!Specifying a Device Name For a} +\index[general]{Specifying a Device Name For a File} + +If you are attempting to read or write an archive file rather than a tape, the +{\bf device-name} should be the full path to the archive location including +the filename. The filename (last part of the specification) will be stripped +and used as the Volume name, and the path (first part before the filename) +must have the same entry in the configuration file. So, the path is equivalent +to the archive device name, and the filename is equivalent to the volume name. + + +\section{Specifying Volumes} +\index[general]{Volumes!Specifying} +\index[general]{Specifying Volumes} + +In general, you must specify the Volume name to each of the programs below +(with the exception of {\bf btape}). The best method to do so is to specify a +{\bf bootstrap} file on the command line with the {\bf -b} option. As part of +the bootstrap file, you will then specify the Volume name or Volume names if +more than one volume is needed. For example, suppose you want to read tapes +{\bf tape1} and {\bf tape2}. First construct a {\bf bootstrap} file named say, +{\bf list.bsr} which contains: + +\footnotesize +\begin{verbatim} +Volume=test1|test2 +\end{verbatim} +\normalsize + +where each Volume is separated by a vertical bar. Then simply use: + +\footnotesize +\begin{verbatim} +./bls -b list.bsr /dev/nst0 +\end{verbatim} +\normalsize + +In the case of Bacula Volumes that are on files, you may simply append volumes +as follows: + +\footnotesize +\begin{verbatim} +./bls /tmp/test1\|test2 +\end{verbatim} +\normalsize + +where the backslash (\textbackslash{}) was necessary as a shell escape to +permit entering the vertical bar (|). + +And finally, if you feel that specifying a Volume name is a bit complicated +with a bootstrap file, you can use the {\bf -V} option (on all programs except +{\bf bcopy}) to specify one or more Volume names separated by the vertical bar +(|). For example, + +\footnotesize +\begin{verbatim} +./bls -V Vol001 /dev/nst0 +\end{verbatim} +\normalsize + +You may also specify an asterisk (*) to indicate that the program should +accept any volume. For example: + +\footnotesize +\begin{verbatim} +./bls -V* /dev/nst0 +\end{verbatim} +\normalsize + +\section{bls} +\label{bls} +\index[general]{bls} +\index[general]{program!bls} + +{\bf bls} can be used to do an {\bf ls} type listing of a {\bf Bacula} tape or +file. It is called: + +\footnotesize +\begin{verbatim} +Usage: bls [options] + -b specify a bootstrap file + -c specify a config file + -d specify debug level + -e exclude list + -i include list + -j list jobs + -k list blocks + (no j or k option) list saved files + -L dump label + -p proceed inspite of errors + -v be verbose + -V specify Volume names (separated by |) + -? print this message +\end{verbatim} +\normalsize + +For example, to list the contents of a tape: + +\footnotesize +\begin{verbatim} +./bls -V Volume-name /dev/nst0 +\end{verbatim} +\normalsize + +Or to list the contents of a file: + +\footnotesize +\begin{verbatim} +./bls /tmp/Volume-name +or +./bls -V Volume-name /tmp +\end{verbatim} +\normalsize + +Note that, in the case of a file, the Volume name becomes the filename, so in +the above example, you will replace the {\bf xxx} with the name of the volume +(file) you wrote. + +Normally if no options are specified, {\bf bls} will produce the equivalent +output to the {\bf ls -l} command for each file on the tape. Using other +options listed above, it is possible to display only the Job records, only the +tape blocks, etc. For example: + +\footnotesize +\begin{verbatim} + +./bls /tmp/File002 +bls: butil.c:148 Using device: /tmp +drwxrwxr-x 3 k k 4096 02-10-19 21:08 /home/kern/bacula/k/src/dird/ +drwxrwxr-x 2 k k 4096 02-10-10 18:59 /home/kern/bacula/k/src/dird/CVS/ +-rw-rw-r-- 1 k k 54 02-07-06 18:02 /home/kern/bacula/k/src/dird/CVS/Root +-rw-rw-r-- 1 k k 16 02-07-06 18:02 /home/kern/bacula/k/src/dird/CVS/Repository +-rw-rw-r-- 1 k k 1783 02-10-10 18:59 /home/kern/bacula/k/src/dird/CVS/Entries +-rw-rw-r-- 1 k k 97506 02-10-18 21:07 /home/kern/bacula/k/src/dird/Makefile +-rw-r--r-- 1 k k 3513 02-10-18 21:02 /home/kern/bacula/k/src/dird/Makefile.in +-rw-rw-r-- 1 k k 4669 02-07-06 18:02 /home/kern/bacula/k/src/dird/README-config +-rw-r--r-- 1 k k 4391 02-09-14 16:51 /home/kern/bacula/k/src/dird/authenticate.c +-rw-r--r-- 1 k k 3609 02-07-07 16:41 /home/kern/bacula/k/src/dird/autoprune.c +-rw-rw-r-- 1 k k 4418 02-10-18 21:03 /home/kern/bacula/k/src/dird/bacula-dir.conf +... +-rw-rw-r-- 1 k k 83 02-08-31 19:19 /home/kern/bacula/k/src/dird/.cvsignore +bls: Got EOF on device /tmp +84 files found. +\end{verbatim} +\normalsize + +\subsection{Listing Jobs} +\index[general]{Listing Jobs with bls} +\index[general]{bls!Listing Jobs} + +If you are listing a Volume to determine what Jobs to restore, normally the +{\bf -j} option provides you with most of what you will need as long as you +don't have multiple clients. For example, + +\footnotesize +\begin{verbatim} +./bls -j -V Test1 -c stored.conf DDS-4 +bls: butil.c:258 Using device: "DDS-4" for reading. +11-Jul 11:54 bls: Ready to read from volume "Test1" on device "DDS-4" (/dev/nst0). +Volume Record: File:blk=0:1 SessId=4 SessTime=1121074625 JobId=0 DataLen=165 +Begin Job Session Record: File:blk=0:2 SessId=4 SessTime=1121074625 JobId=1 Level=F Type=B +Begin Job Session Record: File:blk=0:3 SessId=5 SessTime=1121074625 JobId=5 Level=F Type=B +Begin Job Session Record: File:blk=0:6 SessId=3 SessTime=1121074625 JobId=2 Level=F Type=B +Begin Job Session Record: File:blk=0:13 SessId=2 SessTime=1121074625 JobId=4 Level=F Type=B +End Job Session Record: File:blk=0:99 SessId=3 SessTime=1121074625 JobId=2 Level=F Type=B + Files=168 Bytes=1,732,978 Errors=0 Status=T +End Job Session Record: File:blk=0:101 SessId=2 SessTime=1121074625 JobId=4 Level=F Type=B + Files=168 Bytes=1,732,978 Errors=0 Status=T +End Job Session Record: File:blk=0:108 SessId=5 SessTime=1121074625 JobId=5 Level=F Type=B + Files=168 Bytes=1,732,978 Errors=0 Status=T +End Job Session Record: File:blk=0:109 SessId=4 SessTime=1121074625 JobId=1 Level=F Type=B + Files=168 Bytes=1,732,978 Errors=0 Status=T +11-Jul 11:54 bls: End of Volume at file 1 on device "DDS-4" (/dev/nst0), Volume "Test1" +11-Jul 11:54 bls: End of all volumes. +\end{verbatim} +\normalsize + +shows a full save followed by two incremental saves. + +Adding the {\bf -v} option will display virtually all information that is +available for each record: + +\subsection{Listing Blocks} +\index[general]{Listing Blocks with bls} +\index[general]{bls!Listing Blocks} + +Normally, except for debugging purposes, you will not need to list Bacula +blocks (the "primitive" unit of Bacula data on the Volume). However, you can +do so with: + +\footnotesize +\begin{verbatim} +./bls -k /tmp/File002 +bls: butil.c:148 Using device: /tmp +Block: 1 size=64512 +Block: 2 size=64512 +... +Block: 65 size=64512 +Block: 66 size=19195 +bls: Got EOF on device /tmp +End of File on device +\end{verbatim} +\normalsize + +By adding the {\bf -v} option, you can get more information, which can be +useful in knowing what sessions were written to the volume: + +\footnotesize +\begin{verbatim} +./bls -k -v /tmp/File002 +Volume Label: +Id : Bacula 0.9 mortal +VerNo : 10 +VolName : File002 +PrevVolName : +VolFile : 0 +LabelType : VOL_LABEL +LabelSize : 147 +PoolName : Default +MediaType : File +PoolType : Backup +HostName : +Date label written: 2002-10-19 at 21:16 +Block: 1 blen=64512 First rec FI=VOL_LABEL SessId=1 SessTim=1035062102 Strm=0 rlen=147 +Block: 2 blen=64512 First rec FI=6 SessId=1 SessTim=1035062102 Strm=DATA rlen=4087 +Block: 3 blen=64512 First rec FI=12 SessId=1 SessTim=1035062102 Strm=DATA rlen=5902 +Block: 4 blen=64512 First rec FI=19 SessId=1 SessTim=1035062102 Strm=DATA rlen=28382 +... +Block: 65 blen=64512 First rec FI=83 SessId=1 SessTim=1035062102 Strm=DATA rlen=1873 +Block: 66 blen=19195 First rec FI=83 SessId=1 SessTim=1035062102 Strm=DATA rlen=2973 +bls: Got EOF on device /tmp +End of File on device +\end{verbatim} +\normalsize + +Armed with the SessionId and the SessionTime, you can extract just about +anything. + +If you want to know even more, add a second {\bf -v} to the command line to +get a dump of every record in every block. + +\footnotesize +\begin{verbatim} +./bls -k -v -v /tmp/File002 +bls: block.c:79 Dump block 80f8ad0: size=64512 BlkNum=1 + Hdrcksum=b1bdfd6d cksum=b1bdfd6d +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=VOL_LABEL Strm=0 len=147 p=80f8b40 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=SOS_LABEL Strm=-7 len=122 p=80f8be7 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=1 Strm=UATTR len=86 p=80f8c75 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=2 Strm=UATTR len=90 p=80f8cdf +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=UATTR len=92 p=80f8d4d +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=DATA len=54 p=80f8dbd +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=3 Strm=MD5 len=16 p=80f8e07 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=UATTR len=98 p=80f8e2b +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=DATA len=16 p=80f8ea1 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=4 Strm=MD5 len=16 p=80f8ec5 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=UATTR len=96 p=80f8ee9 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=DATA len=1783 p=80f8f5d +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=5 Strm=MD5 len=16 p=80f9668 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=UATTR len=95 p=80f968c +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=32768 p=80f96ff +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=32768 p=8101713 +bls: block.c:79 Dump block 80f8ad0: size=64512 BlkNum=2 + Hdrcksum=9acc1e7f cksum=9acc1e7f +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=contDATA len=4087 p=80f8b40 +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=DATA len=31970 p=80f9b4b +bls: block.c:92 Rec: VId=1 VT=1035062102 FI=6 Strm=MD5 len=16 p=8101841 +... +\end{verbatim} +\normalsize + +\section{bextract} +\label{bextract} +\index[general]{Bextract} +\index[general]{program!bextract} + +If you find yourself using {\bf bextract}, you probably have done +something wrong. For example, if you are trying to recover a file +but are having problems, please see the \ilink {Restoring When Things Go +Wrong}{database_restore} section of the Restore chapter of this manual. + +Normally, you will restore files by running a {\bf Restore} Job from the {\bf +Console} program. However, {\bf bextract} can be used to extract a single file +or a list of files from a Bacula tape or file. In fact, {\bf bextract} can be +a useful tool to restore files to an empty system assuming you are able to +boot, you have statically linked {\bf bextract} and you have an appropriate +{\bf bootstrap} file. + +Please note that some of the current limitations of bextract are: + +\begin{enumerate} +\item It cannot restore access control lists (ACL) that have been + backed up along with the file data. +\item It cannot restore Win32 non-portable streams (typically default). +\item It cannot restore encrypted files. +\item The command line length is relatively limited, + which means that you cannot enter a huge number of volumes. If you need to + enter more volumes than the command line supports, please use a bootstrap + file (see below). +\end{enumerate} + + +It is called: + +\footnotesize +\begin{verbatim} + +Usage: bextract [-d debug_level] + -b specify a bootstrap file + -dnn set debug level to nn + -e exclude list + -i include list + -p proceed inspite of I/O errors + -V specify Volume names (separated by |) + -? print this message +\end{verbatim} +\normalsize + +where {\bf device-name} is the Archive Device (raw device name or full +filename) of the device to be read, and {\bf directory-to-store-files} is a +path prefix to prepend to all the files restored. + +NOTE: On Windows systems, if you specify a prefix of say d:/tmp, any file that +would have been restored to {\bf c:/My Documents} will be restored to {\bf +d:/tmp/My Documents}. That is, the original drive specification will be +stripped. If no prefix is specified, the file will be restored to the original +drive. + +\subsection{Extracting with Include or Exclude Lists} +\index[general]{Lists!Extracting with Include or Exclude} +\index[general]{Extracting with Include or Exclude Lists} + +Using the {\bf -e} option, you can specify a file containing a list of files +to be excluded. Wildcards can be used in the exclusion list. This option will +normally be used in conjunction with the {\bf -i} option (see below). Both the +{\bf -e} and the {\bf -i} options may be specified at the same time as the +{\bf -b} option. The bootstrap filters will be applied first, then the include +list, then the exclude list. + +Likewise, and probably more importantly, with the {\bf -i} option, you can +specify a file that contains a list (one file per line) of files and +directories to include to be restored. The list must contain the full filename +with the path. If you specify a path name only, all files and subdirectories +of that path will be restored. If you specify a line containing only the +filename (e.g. {\bf my-file.txt}) it probably will not be extracted because +you have not specified the full path. + +For example, if the file {\bf include-list} contains: + +\footnotesize +\begin{verbatim} +/home/kern/bacula +/usr/local/bin +\end{verbatim} +\normalsize + +Then the command: + +\footnotesize +\begin{verbatim} +./bextract -i include-list -V Volume /dev/nst0 /tmp +\end{verbatim} +\normalsize + +will restore from the Bacula archive {\bf /dev/nst0} all files and directories +in the backup from {\bf /home/kern/bacula} and from {\bf /usr/local/bin}. The +restored files will be placed in a file of the original name under the +directory {\bf /tmp} (i.e. /tmp/home/kern/bacula/... and +/tmp/usr/local/bin/...). + +\subsection{Extracting With a Bootstrap File} +\index[general]{File!Extracting With a Bootstrap} +\index[general]{Extracting With a Bootstrap File} + +The {\bf -b} option is used to specify a {\bf bootstrap} file containing the +information needed to restore precisely the files you want. Specifying a {\bf +bootstrap} file is optional but recommended because it gives you the most +control over which files will be restored. For more details on the {\bf +bootstrap} file, please see +\ilink{Restoring Files with the Bootstrap File}{BootstrapChapter} +chapter of this document. Note, you may also use a bootstrap file produced by +the {\bf restore} command. For example: + +\footnotesize +\begin{verbatim} +./bextract -b bootstrap-file /dev/nst0 /tmp +\end{verbatim} +\normalsize + +The bootstrap file allows detailed specification of what files you want +restored (extracted). You may specify a bootstrap file and include and/or +exclude files at the same time. The bootstrap conditions will first be +applied, and then each file record seen will be compared to the include and +exclude lists. + +\subsection{Extracting From Multiple Volumes} +\index[general]{Volumes!Extracting From Multiple} +\index[general]{Extracting From Multiple Volumes} + +If you wish to extract files that span several Volumes, you can specify the +Volume names in the bootstrap file or you may specify the Volume names on the +command line by separating them with a vertical bar. See the section above +under the {\bf bls} program entitled {\bf Listing Multiple Volumes} for more +information. The same techniques apply equally well to the {\bf bextract} +program or read the \ilink{Bootstrap}{BootstrapChapter} +chapter of this document. + +\section{bscan} +\label{bscan} +\index[general]{bscan} +\index[general]{program!bscan} + +If you find yourself using this program, you have probably done something +wrong. For example, the best way to recover a lost or damaged Bacula +database is to reload the database by using the bootstrap file that +was written when you saved it (default bacula-dir.conf file). + +The {\bf bscan} program can be used to re-create a database (catalog) +records from the backup information written to one or more Volumes. +This is normally +needed only if one or more Volumes have been pruned or purged from your +catalog so that the records on the Volume are no longer in the catalog, or +for Volumes that you have archived. + +With some care, it can also be used to synchronize your existing catalog with +a Volume. Although we have never seen a case of bscan damaging a +catalog, since bscan modifies your catalog, we recommend that +you do a simple ASCII backup of your database before running {\bf bscan} just +to be sure. See \ilink{Compacting Your Database}{CompactingMySQL} for +the details of making a copy of your database. + +{\bf bscan} can also be useful in a disaster recovery situation, after the +loss of a hard disk, if you do not have a valid {\bf bootstrap} file for +reloading your system, or if a Volume has been recycled but not overwritten, +you can use {\bf bscan} to re-create your database, which can then be used to +{\bf restore} your system or a file to its previous state. + +It is called: + +\footnotesize +\begin{verbatim} + +Usage: bscan [options] + -b bootstrap specify a bootstrap file + -c specify configuration file + -d set debug level to nn + -m update media info in database + -n specify the database name (default bacula) + -u specify database user name (default bacula) + -P specify database password (default none) + -h specify database host (default NULL) + -p proceed inspite of I/O errors + -r list records + -s synchronize or store in database + -v verbose + -V specify Volume names (separated by |) + -w specify working directory (default from conf file) + -? print this message +\end{verbatim} +\normalsize + +If you are using MySQL or PostgreSQL, there is no need to supply a working +directory since in that case, bscan knows where the databases are. However, if +you have provided security on your database, you may need to supply either the +database name ({\bf -b} option), the user name ({\bf -u} option), and/or the +password ({\bf -p}) options. + +NOTE: before {\bf bscan} can work, it needs at least a bare bones valid +database. If your database exists but some records are missing because +they were pruned, then you are all set. If your database was lost or +destroyed, then you must first ensure that you have the SQL program running +(MySQL or PostgreSQL), then you must create the Bacula database (normally +named bacula), and you must create the Bacula tables using the scripts in +the {\bf cats} directory. This is explained in the +\ilink{Installation}{CreateDatabase} chapter of the manual. Finally, before +scanning into an empty database, you must start and stop the Director with +the appropriate bacula-dir.conf file so that it can create the Client and +Storage records which are not stored on the Volumes. Without these +records, scanning is unable to connect the Job records to the proper +client. + +Forgetting for the moment the extra complications of a full rebuild of +your catalog, let's suppose that you did a backup to Volumes "Vol001" +and "Vol002", then sometime later all records of one or both those +Volumes were pruned or purged from the +database. By using {\bf bscan} you can recreate the catalog entries for +those Volumes and then use the {\bf restore} command in the Console to restore +whatever you want. A command something like: + +\footnotesize +\begin{verbatim} +bscan -c bacula-sd.conf -v -V Vol001\|Vol002 /dev/nst0 +\end{verbatim} +\normalsize + +will give you an idea of what is going to happen without changing +your catalog. Of course, you may need to change the path to the Storage +daemon's conf file, the Volume name, and your tape (or disk) device name. This +command must read the entire tape, so if it has a lot of data, it may take a +long time, and thus you might want to immediately use the command listed +below. Note, if you are writing to a disk file, replace the device name with +the path to the directory that contains the Volumes. This must correspond to +the Archive Device in the conf file. + +Then to actually write or store the records in the catalog, add the {\bf -s} +option as follows: + +\footnotesize +\begin{verbatim} + bscan -s -m -c bacula-sd.conf -v -V Vol001\|Vol002 /dev/nst0 +\end{verbatim} +\normalsize + +When writing to the database, if bscan finds existing records, it will +generally either update them if something is wrong or leave them alone. Thus +if the Volumes you are scanning are all or partially in the catalog already, no +harm will be done to that existing data. Any missing data will simply be +added. + +If you have multiple tapes, you should scan them with: + +\footnotesize +\begin{verbatim} + bscan -s -m -c bacula-sd.conf -v -V Vol001\|Vol002\|Vol003 /dev/nst0 +\end{verbatim} +\normalsize + +Since there is a limit on the command line length (511 bytes) accepted +by {\bf bscan}, if you have too many Volumes, you will need to manually +create a bootstrap file. See the \ilink{Bootstrap}{BootstrapChapter} +chapter of this manual for more details, in particular the section +entitled \ilink{Bootstrap for bscan}{bscanBootstrap}. + +You should, always try to specify the tapes in the order they are written. +However, bscan can handle scanning tapes that are not sequential. Any +incomplete records at the end of the tape will simply be ignored in that +case. If you are simply repairing an existing catalog, this may be OK, but +if you are creating a new catalog from scratch, it will leave your database +in an incorrect state. If you do not specify all necessary Volumes on a +single bscan command, bscan will not be able to correctly restore the +records that span two volumes. In other words, it is much better to +specify two or three volumes on a single bscan command rather than run +bscan two or three times, each with a single volume. + + +Note, the restoration process using bscan is not identical to the original +creation of the catalog data. This is because certain data such as Client +records and other non-essential data such +as volume reads, volume mounts, etc is not stored on the Volume, and thus is +not restored by bscan. The results of bscanning are, however, perfectly valid, +and will permit restoration of any or all the files in the catalog using the +normal Bacula console commands. If you are starting with an empty catalog +and expecting bscan to reconstruct it, you may be a bit disappointed, but +at a minimum, you must ensure that your bacula-dir.conf file is the same +as what it previously was -- that is, it must contain all the appropriate +Client resources so that they will be recreated in your new database {\bf +before} running bscan. Normally when the Director starts, it will recreate +any missing Client records in the catalog. Another problem you will have +is that even if the Volumes (Media records) are recreated in the database, +they will not have their autochanger status and slots properly set. As a +result, you will need to repair that by using the {\bf update slots} +command. There may be other considerations as well. Rather than +bscanning, you should always attempt to recover you previous catalog +backup. + + +\subsection{Using bscan to Compare a Volume to an existing Catalog} +\index[general]{Catalog!Using bscan to Compare a Volume to an existing} +\index[general]{Using bscan to Compare a Volume to an existing Catalog} + +If you wish to compare the contents of a Volume to an existing catalog without +changing the catalog, you can safely do so if and only if you do {\bf not} +specify either the {\bf -m} or the {\bf -s} options. However, at this time +(Bacula version 1.26), the comparison routines are not as good or as thorough +as they should be, so we don't particularly recommend this mode other than for +testing. + +\subsection{Using bscan to Recreate a Catalog from a Volume} +\index[general]{Volume!Using bscan to Recreate a Catalog from a Volume} +\index[general]{Using bscan to Recreate a Catalog from a Volume} + +This is the mode for which {\bf bscan} is most useful. You can either {\bf +bscan} into a freshly created catalog, or directly into your existing catalog +(after having made an ASCII copy as described above). Normally, you should +start with a freshly created catalog that contains no data. + +Starting with a single Volume named {\bf TestVolume1}, you run a command such +as: + +\footnotesize +\begin{verbatim} +./bscan -V TestVolume1 -v -s -m -c bacula-sd.conf /dev/nst0 +\end{verbatim} +\normalsize + +If there is more than one volume, simply append it to the first one separating +it with a vertical bar. You may need to precede the vertical bar with a +forward slash escape the shell -- e.g. {\bf +TestVolume1\textbackslash{}|TestVolume2}. The {\bf -v} option was added for +verbose output (this can be omitted if desired). The {\bf -s} option that +tells {\bf bscan} to store information in the database. The physical device +name {\bf /dev/nst0} is specified after all the options. + +{\bf} For example, after having done a full backup of a directory, then two +incrementals, I reinitialized the SQLite database as described above, and +using the bootstrap.bsr file noted above, I entered the following command: + +\footnotesize +\begin{verbatim} +./bscan -b bootstrap.bsr -v -s -c bacula-sd.conf /dev/nst0 +\end{verbatim} +\normalsize + +which produced the following output: + +\footnotesize +\begin{verbatim} +bscan: bscan.c:182 Using Database: bacula, User: bacula +bscan: bscan.c:673 Created Pool record for Pool: Default +bscan: bscan.c:271 Pool type "Backup" is OK. +bscan: bscan.c:632 Created Media record for Volume: TestVolume1 +bscan: bscan.c:298 Media type "DDS-4" is OK. +bscan: bscan.c:307 VOL_LABEL: OK for Volume: TestVolume1 +bscan: bscan.c:693 Created Client record for Client: Rufus +bscan: bscan.c:769 Created new JobId=1 record for original JobId=2 +bscan: bscan.c:717 Created FileSet record "Kerns Files" +bscan: bscan.c:819 Updated Job termination record for new JobId=1 +bscan: bscan.c:905 Created JobMedia record JobId 1, MediaId 1 +bscan: Got EOF on device /dev/nst0 +bscan: bscan.c:693 Created Client record for Client: Rufus +bscan: bscan.c:769 Created new JobId=2 record for original JobId=3 +bscan: bscan.c:708 Fileset "Kerns Files" already exists. +bscan: bscan.c:819 Updated Job termination record for new JobId=2 +bscan: bscan.c:905 Created JobMedia record JobId 2, MediaId 1 +bscan: Got EOF on device /dev/nst0 +bscan: bscan.c:693 Created Client record for Client: Rufus +bscan: bscan.c:769 Created new JobId=3 record for original JobId=4 +bscan: bscan.c:708 Fileset "Kerns Files" already exists. +bscan: bscan.c:819 Updated Job termination record for new JobId=3 +bscan: bscan.c:905 Created JobMedia record JobId 3, MediaId 1 +bscan: Got EOF on device /dev/nst0 +bscan: bscan.c:652 Updated Media record at end of Volume: TestVolume1 +bscan: bscan.c:428 End of Volume. VolFiles=3 VolBlocks=57 VolBytes=10,027,437 +\end{verbatim} +\normalsize + +The key points to note are that {\bf bscan} prints a line when each major +record is created. Due to the volume of output, it does not print a line for +each file record unless you supply the {\bf -v} option twice or more on the +command line. + +In the case of a Job record, the new JobId will not normally be the same as +the original Jobid. For example, for the first JobId above, the new JobId is +1, but the original JobId is 2. This is nothing to be concerned about as it is +the normal nature of databases. {\bf bscan} will keep everything straight. + +Although {\bf bscan} claims that it created a Client record for Client: Rufus +three times, it was actually only created the first time. This is normal. + +You will also notice that it read an end of file after each Job (Got EOF on +device ...). Finally the last line gives the total statistics for the bscan. + +If you had added a second {\bf -v} option to the command line, Bacula would +have been even more verbose, dumping virtually all the details of each Job +record it encountered. + +Now if you start Bacula and enter a {\bf list jobs} command to the console +program, you will get: + +\footnotesize +\begin{verbatim} ++-------+----------+------------------+------+-----+----------+----------+---------+ +| JobId | Name | StartTime | Type | Lvl | JobFiles | JobBytes | JobStat | ++-------+----------+------------------+------+-----+----------+----------+---------+ +| 1 | kernsave | 2002-10-07 14:59 | B | F | 84 | 4180207 | T | +| 2 | kernsave | 2002-10-07 15:00 | B | I | 15 | 2170314 | T | +| 3 | kernsave | 2002-10-07 15:01 | B | I | 33 | 3662184 | T | ++-------+----------+------------------+------+-----+----------+----------+---------+ +\end{verbatim} +\normalsize + +which corresponds virtually identically with what the database contained +before it was re-initialized and restored with bscan. All the Jobs and Files +found on the tape are restored including most of the Media record. The Volume +(Media) records restored will be marked as {\bf Full} so that they cannot be +rewritten without operator intervention. + +It should be noted that {\bf bscan} cannot restore a database to the exact +condition it was in previously because a lot of the less important information +contained in the database is not saved to the tape. Nevertheless, the +reconstruction is sufficiently complete, that you can run {\bf restore} +against it and get valid results. + +An interesting aspect of restoring a catalog backup using {\bf bscan} is +that the backup was made while Bacula was running and writing to a tape. At +the point the backup of the catalog is made, the tape Bacula is writing to +will have say 10 files on it, but after the catalog backup is made, there +will be 11 files on the tape Bacula is writing. This there is a difference +between what is contained in the backed up catalog and what is actually on +the tape. If after restoring a catalog, you attempt to write on the same +tape that was used to backup the catalog, Bacula will detect the difference +in the number of files registered in the catalog compared to what is on the +tape, and will mark the tape in error. + +There are two solutions to this problem. The first is possibly the simplest +and is to mark the volume as Used before doing any backups. The second is +to manually correct the number of files listed in the Media record of the +catalog. This procedure is documented elsewhere in the manual and involves +using the {\bf update volume} command in {\bf bconsole}. + +\subsection{Using bscan to Correct the Volume File Count} +\index[general]{Using bscan to Correct the Volume File Count} +\index[general]{Count!Using bscan to Correct the Volume File Count} + +If the Storage daemon crashes during a backup Job, the catalog will not be +properly updated for the Volume being used at the time of the crash. This +means that the Storage daemon will have written say 20 files on the tape, but +the catalog record for the Volume indicates only 19 files. + +Bacula refuses to write on a tape that contains a different number of files +from what is in the catalog. To correct this situation, you may run a {\bf +bscan} with the {\bf -m} option (but {\bf without} the {\bf -s} option) to +update only the final Media record for the Volumes read. + +\subsection{After bscan} +\index[general]{After bscan} +\index[general]{Bscan!After} + +If you use {\bf bscan} to enter the contents of the Volume into an existing +catalog, you should be aware that the records you entered may be immediately +pruned during the next job, particularly if the Volume is very old or had been +previously purged. To avoid this, after running {\bf bscan}, you can manually +set the volume status (VolStatus) to {\bf Read-Only} by using the {\bf update} +command in the catalog. This will allow you to restore from the volume without +having it immediately purged. When you have restored and backed up the data, +you can reset the VolStatus to {\bf Used} and the Volume will be purged from +the catalog. + +\section{bcopy} +\label{bcopy} +\index[general]{Bcopy} +\index[general]{program!bcopy} + +The {\bf bcopy} program can be used to copy one {\bf Bacula} archive file to +another. For example, you may copy a tape to a file, a file to a tape, a file +to a file, or a tape to a tape. For tape to tape, you will need two tape +drives. (a later version is planned that will buffer it to disk). In the +process of making the copy, no record of the information written to the new +Volume is stored in the catalog. This means that the new Volume, though it +contains valid backup data, cannot be accessed directly from existing catalog +entries. If you wish to be able to use the Volume with the Console restore +command, for example, you must first bscan the new Volume into the catalog. + +\subsection{bcopy Command Options} +\index[general]{Options!bcopy Command} +\index[general]{Bcopy Command Options} + +\footnotesize +\begin{verbatim} +Usage: bcopy [-d debug_level] + -b bootstrap specify a bootstrap file + -c specify configuration file + -dnn set debug level to nn + -i specify input Volume names (separated by |) + -o specify output Volume names (separated by |) + -p proceed inspite of I/O errors + -v verbose + -w dir specify working directory (default /tmp) + -? print this message +\end{verbatim} +\normalsize + +By using a {\bf bootstrap} file, you can copy parts of a Bacula archive file +to another archive. + +One of the objectives of this program is to be able to recover as much data as +possible from a damaged tape. However, the current version does not yet have +this feature. + +As this is a new program, any feedback on its use would be appreciated. In +addition, I only have a single tape drive, so I have never been able to test +this program with two tape drives. + +\section{btape} +\label{btape} +\index[general]{Btape} +\index[general]{program!btape} + +This program permits a number of elementary tape operations via a tty command +interface. It works only with tapes and not with other kinds of Bacula +storage media (DVD, File, ...). The {\bf test} command, described below, +can be very useful for testing older tape drive compatibility problems. +Aside from initial testing of tape drive compatibility with {\bf Bacula}, +{\bf btape} will be mostly used by developers writing new tape drivers. + +{\bf btape} can be dangerous to use with existing {\bf Bacula} tapes because +it will relabel a tape or write on the tape if so requested regardless that +the tape may contain valuable data, so please be careful and use it only on +blank tapes. + +To work properly, {\bf btape} needs to read the Storage daemon's configuration +file. As a default, it will look for {\bf bacula-sd.conf} in the current +directory. If your configuration file is elsewhere, please use the {\bf -c} +option to specify where. + +The physical device name must be specified on the command line, and this +same device name must be present in the Storage daemon's configuration file +read by {\bf btape} + +\footnotesize +\begin{verbatim} +Usage: btape + -b specify bootstrap file + -c set configuration file to file + -d set debug level to nn + -p proceed inspite of I/O errors + -s turn off signals + -v be verbose + -? print this message. +\end{verbatim} +\normalsize + +\subsection{Using btape to Verify your Tape Drive} +\index[general]{Using btape to Verify your Tape Drive} +\index[general]{Drive!Using btape to Verify your Tape} + +An important reason for this program is to ensure that a Storage daemon +configuration file is defined so that Bacula will correctly read and write +tapes. + +It is highly recommended that you run the {\bf test} command before running +your first Bacula job to ensure that the parameters you have defined for your +storage device (tape drive) will permit {\bf Bacula} to function properly. You +only need to mount a blank tape, enter the command, and the output should be +reasonably self explanatory. Please see the +\ilink{Tape Testing}{TapeTestingChapter} Chapter of this manual for +the details. + +\subsection{btape Commands} +\index[general]{Btape Commands} +\index[general]{Commands!btape} + +The full list of commands are: + +\footnotesize +\begin{verbatim} + Command Description + ======= =========== + autochanger test autochanger + bsf backspace file + bsr backspace record + cap list device capabilities + clear clear tape errors + eod go to end of Bacula data for append + eom go to the physical end of medium + fill fill tape, write onto second volume + unfill read filled tape + fsf forward space a file + fsr forward space a record + help print this command + label write a Bacula label to the tape + load load a tape + quit quit btape + rawfill use write() to fill tape + readlabel read and print the Bacula tape label + rectest test record handling functions + rewind rewind the tape + scan read() tape block by block to EOT and report + scanblocks Bacula read block by block to EOT and report + status print tape status + test General test Bacula tape functions + weof write an EOF on the tape + wr write a single Bacula block + rr read a single record + qfill quick fill command +\end{verbatim} +\normalsize + +The most useful commands are: + +\begin{itemize} +\item test -- test writing records and EOF marks and reading them back. +\item fill -- completely fill a volume with records, then write a few records + on a second volume, and finally, both volumes will be read back. + This command writes blocks containing random data, so your drive will + not be able to compress the data, and thus it is a good test of + the real physical capacity of your tapes. +\item readlabel -- read and dump the label on a Bacula tape. +\item cap -- list the device capabilities as defined in the configuration + file and as perceived by the Storage daemon. + \end{itemize} + +The {\bf readlabel} command can be used to display the details of a Bacula +tape label. This can be useful if the physical tape label was lost or damaged. + + +In the event that you want to relabel a {\bf Bacula}, you can simply use the +{\bf label} command which will write over any existing label. However, please +note for labeling tapes, we recommend that you use the {\bf label} command in +the {\bf Console} program since it will never overwrite a valid Bacula tape. + +\section{Other Programs} +\index[general]{Programs!Other} +\index[general]{Other Programs} + +The following programs are general utility programs and in general do not need +a configuration file nor a device name. + +\section{bsmtp} +\label{bsmtp} +\index[general]{Bsmtp} +\index[general]{program!bsmtp} + +{\bf bsmtp} is a simple mail transport program that permits more flexibility +than the standard mail programs typically found on Unix systems. It can even +be used on Windows machines. + +It is called: + +\footnotesize +\begin{verbatim} +Usage: bsmtp [-f from] [-h mailhost] [-s subject] [-c copy] [recipient ...] + -c set the Cc: field + -dnn set debug level to nn + -f set the From: field + -h use mailhost:port as the bsmtp server + -l limit the lines accepted to nn + -s set the Subject: field + -? print this message. +\end{verbatim} +\normalsize + +If the {\bf -f} option is not specified, {\bf bsmtp} will use your userid. If +the option {\bf -h} is not specified {\bf bsmtp} will use the value in the environment +variable {\bf bsmtpSERVER} or if there is none {\bf localhost}. By default +port 25 is used. + +If a line count limit is set with the {\bf -l} option, {\bf bsmtp} will +not send an email with a body text exceeding that number of lines. This +is especially useful for large restore job reports where the list of +files restored might produce very long mails your mail-server would +refuse or crash. However, be aware that you will probably suppress the +job report and any error messages unless you check the log file written +by the Director (see the messages resource in this manual for details). + + +{\bf recipients} is a space separated list of email recipients. + +The body of the email message is read from standard input. + +An example of the use of {\bf bsmtp} would be to put the following statement +in the {\bf Messages} resource of your {\bf bacula-dir.conf} file. Note, these +commands should appear on a single line each. + +\footnotesize +\begin{verbatim} + mailcommand = "/home/bacula/bin/bsmtp -h mail.domain.com -f \"\(Bacula\) %r\" + -s \"Bacula: %t %e of %c %l\" %r" + operatorcommand = "/home/bacula/bin/bsmtp -h mail.domain.com -f \"\(Bacula\) %r\" + -s \"Bacula: Intervention needed for %j\" %r" +\end{verbatim} +\normalsize + +Where you replace {\bf /home/bacula/bin} with the path to your {\bf Bacula} +binary directory, and you replace {\bf mail.domain.com} with the fully +qualified name of your bsmtp (email) server, which normally listens on port +25. For more details on the substitution characters (e.g. \%r) used in the +above line, please see the documentation of the +\ilink{ MailCommand in the Messages Resource}{mailcommand} +chapter of this manual. + +It is HIGHLY recommended that you test one or two cases by hand to make sure +that the {\bf mailhost} that you specified is correct and that it will accept +your email requests. Since {\bf bsmtp} always uses a TCP connection rather +than writing in the spool file, you may find that your {\bf from} address is +being rejected because it does not contain a valid domain, or because your +message is caught in your spam filtering rules. Generally, you should specify +a fully qualified domain name in the {\bf from} field, and depending on +whether your bsmtp gateway is Exim or Sendmail, you may need to modify the +syntax of the from part of the message. Please test. + +When running {\bf bsmtp} by hand, you will need to terminate the message by +entering a ctl-d in column 1 of the last line. +% TODO: is "column" the correct terminology for this? + +If you are getting incorrect dates (e.g. 1970) and you are +running with a non-English language setting, you might try adding +a LANG=''en\_US'' immediately before the bsmtp call. + +\section{dbcheck} +\label{dbcheck} +\index[general]{Dbcheck} +\index[general]{program!dbcheck} +{\bf dbcheck} is a simple program that will search for logical +inconsistencies in the Bacula tables in your database, and optionally fix them. +It is a database maintenance routine, in the sense that it can +detect and remove unused rows, but it is not a database repair +routine. To repair a database, see the tools furnished by the +database vendor. Normally dbcheck should never need to be run, +but if Bacula has crashed or you have a lot of Clients, Pools, or +Jobs that you have removed, it could be useful. + +The {\bf dbcheck} program can be found in +the {\bf \lt{}bacula-source\gt{}/src/tools} directory of the source +distribution. Though it is built with the make process, it is not normally +"installed". + +It is called: + +\footnotesize +\begin{verbatim} +Usage: dbcheck [-c config] [-C catalog name] [-d debug_level] + [] + -b batch mode + -C catalog name in the director conf file + -c director conf filename + -dnn set debug level to nn + -f fix inconsistencies + -v verbose + -? print this message +\end{verbatim} +\normalsize + +If the {\bf -c} option is given with the Director's conf file, there is no +need to enter any of the command line arguments, in particular the working +directory as dbcheck will read them from the file. + +If the {\bf -f} option is specified, {\bf dbcheck} will repair ({\bf fix}) the +inconsistencies it finds. Otherwise, it will report only. + +If the {\bf -b} option is specified, {\bf dbcheck} will run in batch mode, and +it will proceed to examine and fix (if -f is set) all programmed inconsistency +checks. If the {\bf -b} option is not specified, {\bf dbcheck} will enter +interactive mode and prompt with the following: + +\footnotesize +\begin{verbatim} +Hello, this is the database check/correct program. +Please select the function you want to perform. + 1) Toggle modify database flag + 2) Toggle verbose flag + 3) Repair bad Filename records + 4) Repair bad Path records + 5) Eliminate duplicate Filename records + 6) Eliminate duplicate Path records + 7) Eliminate orphaned Jobmedia records + 8) Eliminate orphaned File records + 9) Eliminate orphaned Path records + 10) Eliminate orphaned Filename records + 11) Eliminate orphaned FileSet records + 12) Eliminate orphaned Client records + 13) Eliminate orphaned Job records + 14) Eliminate all Admin records + 15) Eliminate all Restore records + 16) All (3-15) + 17) Quit +Select function number: +\end{verbatim} +\normalsize + +By entering 1 or 2, you can toggle the modify database flag (-f option) and +the verbose flag (-v). It can be helpful and reassuring to turn off the modify +database flag, then select one or more of the consistency checks (items 3 +through 9) to see what will be done, then toggle the modify flag on and re-run +the check. + +The inconsistencies examined are the following: + +\begin{itemize} +\item Duplicate filename records. This can happen if you accidentally run two + copies of Bacula at the same time, and they are both adding filenames + simultaneously. It is a rare occurrence, but will create an inconsistent + database. If this is the case, you will receive error messages during Jobs + warning of duplicate database records. If you are not getting these error + messages, there is no reason to run this check. +\item Repair bad Filename records. This checks and corrects filenames that + have a trailing slash. They should not. +\item Repair bad Path records. This checks and corrects path names that do + not have a trailing slash. They should. +\item Duplicate path records. This can happen if you accidentally run two + copies of Bacula at the same time, and they are both adding filenames + simultaneously. It is a rare occurrence, but will create an inconsistent + database. See the item above for why this occurs and how you know it is + happening. +\item Orphaned JobMedia records. This happens when a Job record is deleted + (perhaps by a user issued SQL statement), but the corresponding JobMedia + record (one for each Volume used in the Job) was not deleted. Normally, this + should not happen, and even if it does, these records generally do not take + much space in your database. However, by running this check, you can + eliminate any such orphans. +\item Orphaned File records. This happens when a Job record is deleted + (perhaps by a user issued SQL statement), but the corresponding File record + (one for each Volume used in the Job) was not deleted. Note, searching for + these records can be {\bf very} time consuming (i.e. it may take hours) for a + large database. Normally this should not happen as Bacula takes care to + prevent it. Just the same, this check can remove any orphaned File records. + It is recommended that you run this once a year since orphaned File records + can take a large amount of space in your database. You might + want to ensure that you have indexes on JobId, FilenameId, and + PathId for the File table in your catalog before running this + command. +\item Orphaned Path records. This condition happens any time a directory is + deleted from your system and all associated Job records have been purged. + During standard purging (or pruning) of Job records, Bacula does not check + for orphaned Path records. As a consequence, over a period of time, old + unused Path records will tend to accumulate and use space in your database. + This check will eliminate them. It is recommended that you run this + check at least once a year. +\item Orphaned Filename records. This condition happens any time a file is + deleted from your system and all associated Job records have been purged. + This can happen quite frequently as there are quite a large number of files + that are created and then deleted. In addition, if you do a system update or + delete an entire directory, there can be a very large number of Filename + records that remain in the catalog but are no longer used. + + During standard purging (or pruning) of Job records, Bacula does not check + for orphaned Filename records. As a consequence, over a period of time, old + unused Filename records will accumulate and use space in your database. This + check will eliminate them. It is strongly recommended that you run this check + at least once a year, and for large database (more than 200 Megabytes), it is + probably better to run this once every 6 months. +\item Orphaned Client records. These records can remain in the database long + after you have removed a client. +\item Orphaned Job records. If no client is defined for a job or you do not + run a job for a long time, you can accumulate old job records. This option + allow you to remove jobs that are not attached to any client (and thus + useless). +\item All Admin records. This command will remove all Admin records, + regardless of their age. +\item All Restore records. This command will remove all Restore records, + regardless of their age. +\end{itemize} + +By the way, I personally run dbcheck only where I have messed up +my database due to a bug in developing Bacula code, so normally +you should never need to run dbcheck in spite of the +recommendations given above, which are given so that users don't +waste their time running dbcheck too often. + +\section{bregex} +\label{bregex} +\index[general]{bregex} +\index[general]{program!bregex} + +{\bf bregex} is a simple program that will allow you to test +regular expressions against a file of data. This can be useful +because the regex libraries on most systems differ, and in +addition, regex expressions can be complicated. + +{\bf bregex} is found in the src/tools directory and it is +normally installed with your system binaries. To run it, use: + +\begin{verbatim} +Usage: bregex [-d debug_level] -f + -f specify file of data to be matched + -l suppress line numbers + -n print lines that do not match + -? print this message. +\end{verbatim} + +The \lt{}data-file\gt{} is a filename that contains lines +of data to be matched (or not) against one or more patterns. +When the program is run, it will prompt you for a regular +expression pattern, then apply it one line at a time against +the data in the file. Each line that matches will be printed +preceded by its line number. You will then be prompted again +for another pattern. + +Enter an empty line for a pattern to terminate the program. You +can print only lines that do not match by using the -n option, +and you can suppress printing of line numbers with the -l option. + +This program can be useful for testing regex expressions to be +applied against a list of filenames. + +\section{bwild} +\label{bwild} +\index[general]{bwild} +\index[general]{program!bwild} + +{\bf bwild} is a simple program that will allow you to test +wild-card expressions against a file of data. + +{\bf bwild} is found in the src/tools directory and it is +normally installed with your system binaries. To run it, use: + +\begin{verbatim} +Usage: bwild [-d debug_level] -f + -f specify file of data to be matched + -l suppress line numbers + -n print lines that do not match + -? print this message. +\end{verbatim} + +The \lt{}data-file\gt{} is a filename that contains lines +of data to be matched (or not) against one or more patterns. +When the program is run, it will prompt you for a wild-card +pattern, then apply it one line at a time against +the data in the file. Each line that matches will be printed +preceded by its line number. You will then be prompted again +for another pattern. + +Enter an empty line for a pattern to terminate the program. You +can print only lines that do not match by using the -n option, +and you can suppress printing of line numbers with the -l option. + +This program can be useful for testing wild expressions to be +applied against a list of filenames. + +\section{testfind} +\label{testfind} +\index[general]{Testfind} +\index[general]{program!testfind} + +{\bf testfind} permits listing of files using the same search engine that is +used for the {\bf Include} resource in Job resources. Note, much of the +functionality of this program (listing of files to be included) is present in +the +\ilink{estimate command}{estimate} in the Console program. + +The original use of testfind was to ensure that Bacula's file search engine +was correct and to print some statistics on file name and path length. +However, you may find it useful to see what bacula would do with a given {\bf +Include} resource. The {\bf testfind} program can be found in the {\bf +\lt{}bacula-source\gt{}/src/tools} directory of the source distribution. +Though it is built with the make process, it is not normally "installed". + +It is called: + +\footnotesize +\begin{verbatim} +Usage: testfind [-d debug_level] [-] [pattern1 ...] + -a print extended attributes (Win32 debug) + -dnn set debug level to nn + - read pattern(s) from stdin + -? print this message. +Patterns are used for file inclusion -- normally directories. +Debug level>= 1 prints each file found. +Debug level>= 10 prints path/file for catalog. +Errors are always printed. +Files/paths truncated is a number with len> 255. +Truncation is only in the catalog. +\end{verbatim} +\normalsize + +Where a pattern is any filename specification that is valid within an {\bf +Include} resource definition. If none is specified, {\bf /} (the root +directory) is assumed. For example: + +\footnotesize +\begin{verbatim} +./testfind /bin +\end{verbatim} +\normalsize + +Would print the following: + +\footnotesize +\begin{verbatim} +Dir: /bin +Reg: /bin/bash +Lnk: /bin/bash2 -> bash +Lnk: /bin/sh -> bash +Reg: /bin/cpio +Reg: /bin/ed +Lnk: /bin/red -> ed +Reg: /bin/chgrp +... +Reg: /bin/ipcalc +Reg: /bin/usleep +Reg: /bin/aumix-minimal +Reg: /bin/mt +Lnka: /bin/gawk-3.1.0 -> /bin/gawk +Reg: /bin/pgawk +Total files : 85 +Max file length: 13 +Max path length: 5 +Files truncated: 0 +Paths truncated: 0 +\end{verbatim} +\normalsize + +Even though {\bf testfind} uses the same search engine as {\bf Bacula}, each +directory to be listed, must be entered as a separate command line entry or +entered one line at a time to standard input if the {\bf -} option was +specified. + +Specifying a debug level of one (i.e. {\bf -d1}) on the command line will +cause {\bf testfind} to print the raw filenames without showing the Bacula +internal file type, or the link (if any). Debug levels of 10 or greater cause +the filename and the path to be separated using the same algorithm that is +used when putting filenames into the Catalog database. diff --git a/docs/manuals/fr/utility/rpm-faq.tex b/docs/manuals/fr/utility/rpm-faq.tex new file mode 100644 index 00000000..1e37cc59 --- /dev/null +++ b/docs/manuals/fr/utility/rpm-faq.tex @@ -0,0 +1,394 @@ +%% +%% + +\chapter{Bacula RPM Packaging FAQ} +\label{RpmFaqChapter} +\index[general]{FAQ!Bacula\textsuperscript{\textregistered} - RPM Packaging } +\index[general]{Bacula\textsuperscript{\textregistered} - RPM Packaging FAQ } + +\begin{enumerate} +\item + \ilink{How do I build Bacula for platform xxx?}{faq1} +\item + \ilink{How do I control which database support gets built?}{faq2} + +\item + \ilink{What other defines are used?}{faq3} +\item + \ilink{I'm getting errors about not having permission when I try to build the + packages. Do I need to be root?}{faq4} +\item + \ilink{I'm building my own rpms but on all platforms and compiles I get an + unresolved dependency for something called + /usr/afsws/bin/pagsh.}{faq5} +\item + \ilink{I'm building my own rpms because you don't publish for my platform. + Can I get my packages released to sourceforge for other people to use?}{faq6} +\item + \ilink{Is there an easier way than sorting out all these command line options?}{faq7} +\item + \ilink{I just upgraded from 1.36.x to 1.38.x and now my director daemon won't start. It appears to start but dies silently and I get a "connection refused" error when starting the console. What is wrong?}{faq8} +\item + \ilink{There are a lot of rpm packages. Which packages do I need for what?}{faq9} +\end{enumerate} + +\section{Answers} +\index[general]{Answers } + +\begin{enumerate} +\item + \label{faq1} + {\bf How do I build Bacula for platform xxx?} + The bacula spec file contains defines to build for several platforms: + Red Hat 7.x (rh7), Red Hat 8.0 (rh8), Red Hat 9 (rh9), Fedora Core (fc1, + fc3, fc4, fc5, fc6, fc7), Whitebox Enterprise Linux 3.0 (wb3), Red Hat Enterprise Linux + (rhel3, rhel4, rhel5), Mandrake 10.x (mdk), Mandriva 2006.x (mdv) CentOS (centos3, centos4, centos5) + Scientific Linux (sl3, sl4, sl5) and SuSE (su9, su10, su102, su103). The package build is controlled by a mandatory define set at the beginning of the file. These defines basically just control the dependency information that gets coded into the finished rpm package as well + as any special configure options required. The platform define may be edited + in the spec file directly (by default all defines are set to 0 or "not set"). + For example, to build the Red Hat 7.x package find the line in the spec file + which reads + +\footnotesize +\begin{verbatim} + %define rh7 0 + +\end{verbatim} +\normalsize + +and edit it to read + +\footnotesize +\begin{verbatim} + %define rh7 1 + +\end{verbatim} +\normalsize + +Alternately you may pass the define on the command line when calling rpmbuild: + + +\footnotesize +\begin{verbatim} + rpmbuild -ba --define "build_rh7 1" bacula.spec + rpmbuild --rebuild --define build_rh7 1" bacula-x.x.x-x.src.rpm + +\end{verbatim} +\normalsize + +\item + \label{faq2} + {\bf How do I control which database support gets built?} + Another mandatory build define controls which database support is compiled, + one of build\_sqlite, build\_mysql or build\_postgresql. To get the MySQL + package and support either set the + +\footnotesize +\begin{verbatim} + %define mysql 0 + OR + %define mysql4 0 + OR + %define mysql5 0 + +\end{verbatim} +\normalsize + +to + +\footnotesize +\begin{verbatim} + %define mysql 1 + OR + %define mysql4 1 + OR + %define mysql5 1 + +\end{verbatim} +\normalsize + +in the spec file directly or pass it to rpmbuild on the command line: + +\footnotesize +\begin{verbatim} + rpmbuild -ba --define "build_rh7 1" --define "build_mysql 1" bacula.spec + rpmbuild -ba --define "build_rh7 1" --define "build_mysql4 1" bacula.spec + rpmbuild -ba --define "build_rh7 1" --define "build_mysql5 1" bacula.spec + +\end{verbatim} +\normalsize + +\item + \label{faq3} + {\bf What other defines are used?} + Three other building defines of note are the depkgs\_version, docs\_version and + \_rescuever identifiers. These two defines are set with each release and must + match the version of those sources that are being used to build the packages. + You would not ordinarily need to edit these. See also the Build Options section + below for other build time options that can be passed on the command line. +\item + \label{faq4} + {\bf I'm getting errors about not having permission when I try to build the + packages. Do I need to be root?} + No, you do not need to be root and, in fact, it is better practice to + build rpm packages as a non-root user. Bacula packages are designed to + be built by a regular user but you must make a few changes on your + system to do this. If you are building on your own system then the + simplest method is to add write permissions for all to the build + directory (/usr/src/redhat/, /usr/src/RPM or /usr/src/packages). + To accomplish this, execute the following command as root: + +\footnotesize +\begin{verbatim} + chmod -R 777 /usr/src/redhat + chmod -R 777 /usr/src/RPM + chmod -R 777 /usr/src/packages + +\end{verbatim} +\normalsize + +If you are working on a shared system where you can not use the method +above then you need to recreate the appropriate above directory tree with all +of its subdirectories inside your home directory. Then create a file named + +{\tt .rpmmacros} + +in your home directory (or edit the file if it already exists) +and add the following line: + +\footnotesize +\begin{verbatim} + %_topdir /home/myuser/redhat + +\end{verbatim} +\normalsize + +Another handy directive for the .rpmmacros file if you wish to suppress the +creation of debug rpm packages is: + +\footnotesize +\begin{verbatim} + %debug_package %{nil} + +\end{verbatim} + +\normalsize + +\item + \label{faq5} + {\bf I'm building my own rpms but on all platforms and compiles I get an + unresolved dependency for something called /usr/afsws/bin/pagsh.} This + is a shell from the OpenAFS (Andrew File System). If you are seeing + this then you chose to include the docs/examples directory in your + package. One of the example scripts in this directory is a pagsh + script. Rpmbuild, when scanning for dependencies, looks at the shebang + line of all packaged scripts in addition to checking shared libraries. + To avoid this do not package the examples directory. If you are seeing this + problem you are building a very old bacula package as the examples have been + removed from the doc packaging. + +\item + \label{faq6} + {\bf I'm building my own rpms because you don't publish for my platform. + Can I get my packages released to sourceforge for other people to use?} Yes, + contributions from users are accepted and appreciated. Please examine the + directory platforms/contrib-rpm in the source code for further information. + +\item + \label{faq7} + {\bf Is there an easier way than sorting out all these command line options?} Yes, + there is a gui wizard shell script which you can use to rebuild the src rpm package. + Look in the source archive for platforms/contrib-rpm/rpm\_wizard.sh. This script will + allow you to specify build options using GNOME dialog screens. It requires zenity. + +\item + \label{faq8} + {\bf I just upgraded from 1.36.x to 1.38.x and now my director daemon +won't start. It appears to start but dies silently and I get a "connection +refused" error when starting the console. What is wrong?} Beginning with +1.38 the rpm packages are configured to run the director and storage +daemons as a non-root user. The file daemon runs as user root and group +bacula, the storage daemon as user bacula and group disk, and the director +as user bacula and group bacula. If you are upgrading you will need to +change some file permissions for things to work. Execute the following +commands as root: + +\footnotesize +\begin{verbatim} + chown bacula.bacula /var/bacula/* + chown root.bacula /var/bacula/bacula-fd.9102.state + chown bacula.disk /var/bacula/bacula-sd.9103.state + +\end{verbatim} +\normalsize + +Further, if you are using File storage volumes rather than tapes those +files will also need to have ownership set to user bacula and group bacula. + +\item + \label{faq9} + {\bf There are a lot of rpm packages. Which packages do I need for +what?} For a bacula server you need to select the packsge based upon your +preferred catalog database: one of bacula-mysql, bacula-postgresql or +bacula-sqlite. If your system does not provide an mtx package you also +need bacula-mtx to satisfy that dependancy. For a client machine you need +only install bacula-client. Optionally, for either server or client +machines, you may install a graphical console bacula-gconsole and/or +bacula-wxconsole. The Bacula Administration Tool is installed with the +bacula-bat package. One last package, bacula-updatedb is required only when +upgrading a server more than one database revision level. + + + +\item {\bf Support for RHEL3/4/5, CentOS 3/4/5, Scientific Linux 3/4/5 and x86\_64} + The examples below show + explicit build support for RHEL4 and CentOS 4. Build support + for x86\_64 has also been added. +\end{enumerate} + +\footnotesize +\begin{verbatim} +Build with one of these 3 commands: + +rpmbuild --rebuild \ + --define "build_rhel4 1" \ + --define "build_sqlite 1" \ + bacula-1.38.3-1.src.rpm + +rpmbuild --rebuild \ + --define "build_rhel4 1" \ + --define "build_postgresql 1" \ + bacula-1.38.3-1.src.rpm + +rpmbuild --rebuild \ + --define "build_rhel4 1" \ + --define "build_mysql4 1" \ + bacula-1.38.3-1.src.rpm + +For CentOS substitute '--define "build_centos4 1"' in place of rhel4. +For Scientific Linux substitute '--define "build_sl4 1"' in place of rhel4. + +For 64 bit support add '--define "build_x86_64 1"' +\end{verbatim} +\normalsize + +\section{Build Options} +\index[general]{Build Options} +The spec file currently supports building on the following platforms: +\footnotesize +\begin{verbatim} +Red Hat builds +--define "build_rh7 1" +--define "build_rh8 1" +--define "build_rh9 1" + +Fedora Core build +--define "build_fc1 1" +--define "build_fc3 1" +--define "build_fc4 1" +--define "build_fc5 1" +--define "build_fc6 1" +--define "build_fc7 1" + +Whitebox Enterprise build +--define "build_wb3 1" + +Red Hat Enterprise builds +--define "build_rhel3 1" +--define "build_rhel4 1" +--define "build_rhel5 1" + +CentOS build +--define "build_centos3 1" +--define "build_centos4 1" +--define "build_centos5 1" + +Scientific Linux build +--define "build_sl3 1" +--define "build_sl4 1" +--define "build_sl5 1" + +SuSE build +--define "build_su9 1" +--define "build_su10 1" +--define "build_su102 1" +--define "build_su103 1" + +Mandrake 10.x build +--define "build_mdk 1" + +Mandriva build +--define "build_mdv 1" + +MySQL support: +for mysql 3.23.x support define this +--define "build_mysql 1" +if using mysql 4.x define this, +currently: Mandrake 10.x, Mandriva 2006.0, SuSE 9.x & 10.0, FC4 & RHEL4 +--define "build_mysql4 1" +if using mysql 5.x define this, +currently: SuSE 10.1 & FC5 +--define "build_mysql5 1" + +PostgreSQL support: +--define "build_postgresql 1" + +Sqlite support: +--define "build_sqlite 1" + +Build the client rpm only in place of one of the above database full builds: +--define "build_client_only 1" + +X86-64 support: +--define "build_x86_64 1" + +Supress build of bgnome-console: +--define "nobuild_gconsole 1" + +Build the WXWindows console: +requires wxGTK >= 2.6 +--define "build_wxconsole 1" + +Build the Bacula Administration Tool: +requires QT >= 4.2 +--define "build_bat 1" + +Build python scripting support: +--define "build_python 1" + +Modify the Packager tag for third party packages: +--define "contrib_packager Your Name " + +\end{verbatim} +\normalsize + +\section{RPM Install Problems} +\index[general]{RPM Install Problems} +In general the RPMs, once properly built should install correctly. +However, when attempting to run the daemons, a number of problems +can occur: +\begin{itemize} +\item [Wrong /var/bacula Permissions] + By default, the Director and Storage daemon do not run with + root permission. If the /var/bacula is owned by root, then it + is possible that the Director and the Storage daemon will not + be able to access this directory, which is used as the Working + Directory. To fix this, the easiest thing to do is: +\begin{verbatim} + chown bacula:bacula /var/bacula +\end{verbatim} + Note: as of 1.38.8 /var/bacula is installed root:bacula with + permissions 770. +\item [The Storage daemon cannot Access the Tape drive] + This can happen in some older RPM releases where the Storage + daemon ran under userid bacula, group bacula. There are two + ways of fixing this: the best is to modify the /etc/init.d/bacula-sd + file so that it starts the Storage daemon with group "disk". + The second way to fix the problem is to change the permissions + of your tape drive (usually /dev/nst0) so that Bacula can access it. + You will probably need to change the permissions of the SCSI control + device as well, which is usually /dev/sg0. The exact names depend + on your configuration, please see the Tape Testing chapter for + more information on devices. +\end{itemize} + diff --git a/docs/manuals/fr/utility/setup.sm b/docs/manuals/fr/utility/setup.sm new file mode 100644 index 00000000..7c88dc61 --- /dev/null +++ b/docs/manuals/fr/utility/setup.sm @@ -0,0 +1,23 @@ +/* + * html2latex + */ + +available { + sun4_sunos.4 + sun4_solaris.2 + rs_aix.3 + rs_aix.4 + sgi_irix +} + +description { + From Jeffrey Schaefer, Geometry Center. Translates HTML document to LaTeX +} + +install { + bin/html2latex /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex + bin/html2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.tag + bin/html2latex-local.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex-local.tag + bin/webtex2latex.tag /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/webtex2latex.tag + man/man1/html2latex.1 /afs/rpi.edu/dept/acs/rpinfo/filters/GChtml2latex/html2latex.1 +} diff --git a/docs/manuals/fr/utility/translate_images.pl b/docs/manuals/fr/utility/translate_images.pl new file mode 100755 index 00000000..c7225118 --- /dev/null +++ b/docs/manuals/fr/utility/translate_images.pl @@ -0,0 +1,185 @@ +#!/usr/bin/perl -w +# +use strict; + +# Used to change the names of the image files generated by latex2html from imgxx.png +# to meaningful names. Provision is made to go either from or to the meaningful names. +# The meaningful names are obtained from a file called imagename_translations, which +# is generated by extensions to latex2html in the make_image_file subroutine in +# bacula.perl. + +# Opens the file imagename_translations and reads the contents into a hash. +# The hash is creaed with the imgxx.png files as the key if processing TO +# meaningful filenames, and with the meaningful filenames as the key if +# processing FROM meaningful filenames. +# Then opens the html file(s) indicated in the command-line arguments and +# changes all image references according to the translations described in the +# above file. Finally, it renames the image files. +# +# Original creation: 3-27-05 by Karl Cunningham. +# Modified 5-21-05 to go FROM and TO meaningful filenames. +# +my $TRANSFILE = "imagename_translations"; +my $path; + +# Loads the contents of $TRANSFILE file into the hash referenced in the first +# argument. The hash is loaded to translate old to new if $direction is 0, +# otherwise it is loaded to translate new to old. In this context, the +# 'old' filename is the meaningful name, and the 'new' filename is the +# imgxx.png filename. It is assumed that the old image is the one that +# latex2html has used as the source to create the imgxx.png filename. +# The filename extension is taken from the file +sub read_transfile { + my ($trans,$direction) = @_; + + if (!open IN,"<$path$TRANSFILE") { + print "WARNING: Cannot open image translation file $path$TRANSFILE for reading\n"; + print " Image filename translation aborted\n\n"; + exit 0; + } + + while () { + chomp; + my ($new,$old) = split(/\001/); + + # Old filenames will usually have a leading ./ which we don't need. + $old =~ s/^\.\///; + + # The filename extension of the old filename must be made to match + # the new filename because it indicates the encoding format of the image. + my ($ext) = $new =~ /(\.[^\.]*)$/; + $old =~ s/\.[^\.]*$/$ext/; + if ($direction == 0) { + $trans->{$new} = $old; + } else { + $trans->{$old} = $new; + } + } + close IN; +} + +# Translates the image names in the file given as the first argument, according to +# the translations in the hash that is given as the second argument. +# The file contents are read in entirely into a string, the string is processed, and +# the file contents are then written. No particular care is taken to ensure that the +# file is not lost if a system failure occurs at an inopportune time. It is assumed +# that the html files being processed here can be recreated on demand. +# +# Links to other files are added to the %filelist for processing. That way, +# all linked files will be processed (assuming they are local). +sub translate_html { + my ($filename,$trans,$filelist) = @_; + my ($contents,$out,$this,$img,$dest); + my $cnt = 0; + + # If the filename is an external link ignore it. And drop any file:// from + # the filename. + $filename =~ /^(http|ftp|mailto)\:/ and return 0; + $filename =~ s/^file\:\/\///; + # Load the contents of the html file. + if (!open IF,"<$path$filename") { + print "WARNING: Cannot open $path$filename for reading\n"; + print " Image Filename Translation aborted\n\n"; + exit 0; + } + + while () { + $contents .= $_; + } + close IF; + + # Now do the translation... + # First, search for an image filename. + while ($contents =~ /\<\s*IMG[^\>]*SRC=\"/si) { + $contents = $'; + $out .= $` . $&; + + # The next thing is an image name. Get it and translate it. + $contents =~ /^(.*?)\"/s; + $contents = $'; + $this = $&; + $img = $1; + # If the image is in our list of ones to be translated, do it + # and feed the result to the output. + $cnt += $this =~ s/$img/$trans->{$img}/ if (defined($trans->{$img})); + $out .= $this; + } + $out .= $contents; + + # Now send the translated text to the html file, overwriting what's there. + open OF,">$path$filename" or die "Cannot open $path$filename for writing\n"; + print OF $out; + close OF; + + # Now look for any links to other files and add them to the list of files to do. + while ($out =~ /\<\s*A[^\>]*HREF=\"(.*?)\"/si) { + $out = $'; + $dest = $1; + # Drop an # and anything after it. + $dest =~ s/\#.*//; + $filelist->{$dest} = '' if $dest; + } + return $cnt; +} + +# REnames the image files spefified in the %translate hash. +sub rename_images { + my $translate = shift; + my ($response); + + foreach (keys(%$translate)) { + if (! $translate->{$_}) { + print " WARNING: No destination Filename for $_\n"; + } else { + $response = `mv -f $path$_ $path$translate->{$_} 2>&1`; + $response and print "ERROR from system $response\n"; + } + } +} + +################################################# +############# MAIN ############################# +################################################ + +# %filelist starts out with keys from the @ARGV list. As files are processed, +# any links to other files are added to the %filelist. A hash of processed +# files is kept so we don't do any twice. + +# The first argument must be either --to_meaningful_names or --from_meaningful_names + +my (%translate,$search_regex,%filelist,%completed,$thisfile); +my ($cnt,$direction); + +my $arg0 = shift(@ARGV); +$arg0 =~ /^(--to_meaningful_names|--from_meaningful_names)$/ or + die "ERROR: First argument must be either \'--to_meaningful_names\' or \'--from_meaningful_names\'\n"; + +$direction = ($arg0 eq '--to_meaningful_names') ? 0 : 1; + +(@ARGV) or die "ERROR: Filename(s) to process must be given as arguments\n"; + +# Use the first argument to get the path to the file of translations. +my $tmp = $ARGV[0]; +($path) = $tmp =~ /(.*\/)/; +$path = '' unless $path; + +read_transfile(\%translate,$direction); + +foreach (@ARGV) { + # Strip the path from the filename, and use it later on. + if (s/(.*\/)//) { + $path = $1; + } else { + $path = ''; + } + $filelist{$_} = ''; + + while ($thisfile = (keys(%filelist))[0]) { + $cnt += translate_html($thisfile,\%translate,\%filelist) if (!exists($completed{$thisfile})); + delete($filelist{$thisfile}); + $completed{$thisfile} = ''; + } + print "translate_images.pl: $cnt image filenames translated ",($direction)?"from":"to"," meaningful names\n"; +} + +rename_images(\%translate); diff --git a/docs/manuals/fr/utility/update_version b/docs/manuals/fr/utility/update_version new file mode 100755 index 00000000..5c2e0092 --- /dev/null +++ b/docs/manuals/fr/utility/update_version @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' /home/kern/bacula/k/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/utility/update_version.in b/docs/manuals/fr/utility/update_version.in new file mode 100644 index 00000000..2766245f --- /dev/null +++ b/docs/manuals/fr/utility/update_version.in @@ -0,0 +1,10 @@ +#!/bin/sh +# +# Script file to update the Bacula version +# +out=/tmp/$$ +VERSION=`sed -n -e 's/^.*VERSION.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +DATE=`sed -n -e 's/^.*[ \t]*BDATE.*"\(.*\)"$/\1/p' @bacula@/src/version.h` +. ./do_echo +sed -f ${out} version.tex.in >version.tex +rm -f ${out} diff --git a/docs/manuals/fr/utility/utility.tex b/docs/manuals/fr/utility/utility.tex new file mode 100644 index 00000000..2efa5cde --- /dev/null +++ b/docs/manuals/fr/utility/utility.tex @@ -0,0 +1,79 @@ +%% +%% +%% The following characters must be preceded by a backslash +%% to be entered as printable characters: +%% +%% # $ % & ~ _ ^ \ { } +%% + +\documentclass[11pt,a4paper]{book} +\usepackage{html} +\usepackage{float} +\usepackage{graphicx} +\usepackage{bacula} +\usepackage{longtable} +\usepackage{makeidx} +\usepackage{index} +\usepackage{setspace} +\usepackage{hyperref} +\usepackage{url} + + +\makeindex +\newindex{general}{idx}{ind}{General Index} + +\sloppy + +\begin{document} +\sloppy + +\newfont{\bighead}{cmr17 at 36pt} +\parskip 10pt +\parindent 0pt + +\title{\includegraphics{./bacula-logo.eps} \\ \bigskip + \Huge{Bacula Utility Programs} + \begin{center} + \large{It comes in the night and sucks + the essence from your computers. } + \end{center} +} + + +\author{Kern Sibbald} +\date{\vspace{1.0in}\today \\ + This manual documents Bacula version \input{version} \\ + \vspace{0.2in} + Copyright \copyright 1999-2007, Free Software Foundation Europe + e.V. \\ + \vspace{0.2in} + Permission is granted to copy, distribute and/or modify this document under the terms of the + GNU Free Documentation License, Version 1.2 published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. + A copy of the license is included in the section entitled "GNU Free Documentation License". +} + +\maketitle + +\clearpage +\tableofcontents +\clearpage +\listoffigures +\clearpage +\listoftables +\clearpage + +\include{progs} +\include{bimagemgr-chapter} +\include{rpm-faq} +\include{fdl} + + +% The following line tells link_resolver.pl to not include these files: +% nolinks developersi baculai-dir baculai-fd baculai-sd baculai-console baculai-main + +% pull in the index +\clearpage +\printindex[general] + +\end{document} diff --git a/docs/manuals/fr/utility/version.tex b/docs/manuals/fr/utility/version.tex new file mode 100644 index 00000000..82d910aa --- /dev/null +++ b/docs/manuals/fr/utility/version.tex @@ -0,0 +1 @@ +2.3.6 (04 November 2007) diff --git a/docs/manuals/fr/utility/version.tex.in b/docs/manuals/fr/utility/version.tex.in new file mode 100644 index 00000000..ff66dfc6 --- /dev/null +++ b/docs/manuals/fr/utility/version.tex.in @@ -0,0 +1 @@ +@VERSION@ (@DATE@)