diff options
Diffstat (limited to 'doc/latex')
| -rw-r--r-- | doc/latex/Makefile | 64 | ||||
| -rw-r--r-- | doc/latex/fncychap.sty | 683 | ||||
| -rw-r--r-- | doc/latex/manual.aux | 366 | ||||
| -rw-r--r-- | doc/latex/manual.idx | 0 | ||||
| -rw-r--r-- | doc/latex/manual.log | 934 | ||||
| -rw-r--r-- | doc/latex/manual.out | 58 | ||||
| -rw-r--r-- | doc/latex/manual.tex | 2761 | ||||
| -rw-r--r-- | doc/latex/manual.toc | 142 | ||||
| -rw-r--r-- | doc/latex/python.ist | 11 | ||||
| -rw-r--r-- | doc/latex/sphinx.sty | 464 | ||||
| -rw-r--r-- | doc/latex/sphinxhowto.cls | 81 | ||||
| -rw-r--r-- | doc/latex/sphinxmanual.cls | 122 | ||||
| -rw-r--r-- | doc/latex/tabulary.sty | 452 |
13 files changed, 6138 insertions, 0 deletions
diff --git a/doc/latex/Makefile b/doc/latex/Makefile new file mode 100644 index 0000000..f219a2f --- /dev/null +++ b/doc/latex/Makefile @@ -0,0 +1,64 @@ +# Makefile for Sphinx LaTeX output + +ALLDOCS = $(basename $(wildcard *.tex)) +ALLPDF = $(addsuffix .pdf,$(ALLDOCS)) +ALLDVI = $(addsuffix .dvi,$(ALLDOCS)) + +# Prefix for archive names +ARCHIVEPRREFIX = +# Additional LaTeX options +LATEXOPTS = + +all: $(ALLPDF) +all-pdf: $(ALLPDF) +all-dvi: $(ALLDVI) +all-ps: all-dvi + for f in *.dvi; do dvips $$f; done +all-pdf-ja: $(wildcard *.tex) + ebb $(wildcard *.pdf *.png *.gif *.jpeg) + platex -kanji=utf8 $(LATEXOPTS) '$<' + platex -kanji=utf8 $(LATEXOPTS) '$<' + platex -kanji=utf8 $(LATEXOPTS) '$<' + -mendex -U -f -d '$(basename $<).dic' -s python.ist '$(basename $<).idx' + platex -kanji=utf8 $(LATEXOPTS) '$<' + platex -kanji=utf8 $(LATEXOPTS) '$<' + dvipdfmx '$(basename $<).dvi' + +zip: all-$(FMT) + mkdir $(ARCHIVEPREFIX)docs-$(FMT) + cp $(ALLPDF) $(ARCHIVEPREFIX)docs-$(FMT) + zip -q -r -9 $(ARCHIVEPREFIX)docs-$(FMT).zip $(ARCHIVEPREFIX)docs-$(FMT) + rm -r $(ARCHIVEPREFIX)docs-$(FMT) + +tar: all-$(FMT) + mkdir $(ARCHIVEPREFIX)docs-$(FMT) + cp $(ALLPDF) $(ARCHIVEPREFIX)docs-$(FMT) + tar cf $(ARCHIVEPREFIX)docs-$(FMT).tar $(ARCHIVEPREFIX)docs-$(FMT) + rm -r $(ARCHIVEPREFIX)docs-$(FMT) + +bz2: tar + bzip2 -9 -k $(ARCHIVEPREFIX)docs-$(FMT).tar + +# The number of LaTeX runs is quite conservative, but I don't expect it +# to get run often, so the little extra time won't hurt. +%.dvi: %.tex + latex $(LATEXOPTS) '$<' + latex $(LATEXOPTS) '$<' + latex $(LATEXOPTS) '$<' + -makeindex -s python.ist '$(basename $<).idx' + latex $(LATEXOPTS) '$<' + latex $(LATEXOPTS) '$<' + +%.pdf: %.tex + pdflatex $(LATEXOPTS) '$<' + pdflatex $(LATEXOPTS) '$<' + pdflatex $(LATEXOPTS) '$<' + -makeindex -s python.ist '$(basename $<).idx' + pdflatex $(LATEXOPTS) '$<' + pdflatex $(LATEXOPTS) '$<' + +clean: + rm -f *.dvi *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla + +.PHONY: all all-pdf all-dvi all-ps clean + diff --git a/doc/latex/fncychap.sty b/doc/latex/fncychap.sty new file mode 100644 index 0000000..9a56c04 --- /dev/null +++ b/doc/latex/fncychap.sty @@ -0,0 +1,683 @@ +%%% Copyright Ulf A. Lindgren +%%% +%%% Note Premission is granted to modify this file under +%%% the condition that it is saved using another +%%% file and package name. +%%% +%%% Revision 1.1 (1997) +%%% +%%% Jan. 8th Modified package name base date option +%%% Jan. 22th Modified FmN and FmTi for error in book.cls +%%% \MakeUppercase{#}->{\MakeUppercase#} +%%% Apr. 6th Modified Lenny option to prevent undesired +%%% skip of line. +%%% Nov. 8th Fixed \@chapapp for AMS +%%% +%%% Revision 1.2 (1998) +%%% +%%% Feb. 11th Fixed appendix problem related to Bjarne +%%% Aug. 11th Fixed problem related to 11pt and 12pt +%%% suggested by Tomas Lundberg. THANKS! +%%% +%%% Revision 1.3 (2004) +%%% Sep. 20th problem with frontmatter, mainmatter and +%%% backmatter, pointed out by Lapo Mori +%%% +%%% Revision 1.31 (2004) +%%% Sep. 21th problem with the Rejne definition streched text +%%% caused ugly gaps in the vrule aligned with the title +%%% text. Kindly pointed out to me by Hendri Adriaens +%%% +%%% Revision 1.32 (2005) +%%% Jun. 23th compatibility problem with the KOMA class 'scrbook.cls' +%%% a remedy is a redefinition of '\@schapter' in +%%% line with that used in KOMA. The problem was pointed +%%% out to me by Mikkel Holm Olsen +%%% +%%% Revision 1.33 (2005) +%%% Aug. 9th misspelled ``TWELV'' corrected, the error was pointed +%%% out to me by George Pearson +%%% +%%% Revision 1.34 (2007) +%%% Added an alternative to Lenny provided by Peter +%%% Osborne (2005-11-28) +%%% Corrected front, main and back matter, based on input +%%% from Bas van Gils (2006-04-24) +%%% Jul. 30th Added Bjornstrup option provided by Jean-Marc +%%% Francois (2007-01-05). +%%% Reverted to \MakeUppercase{#} see rev 1.1, solved +%%% problem with MakeUppercase and MakeLowercase pointed +%%% out by Marco Feuerstein (2007-06-06) + + +%%% Last modified Jul. 2007 + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesPackage{fncychap} + [2007/07/30 v1.34 + LaTeX package (Revised chapters)] + +%%%% For conditional inclusion of color +\newif\ifusecolor +\usecolorfalse + + + +%%%% DEFINITION OF Chapapp variables +\newcommand{\CNV}{\huge\bfseries} +\newcommand{\ChNameVar}[1]{\renewcommand{\CNV}{#1}} + + +%%%% DEFINITION OF TheChapter variables +\newcommand{\CNoV}{\huge\bfseries} +\newcommand{\ChNumVar}[1]{\renewcommand{\CNoV}{#1}} + +\newif\ifUCN +\UCNfalse +\newif\ifLCN +\LCNfalse +\def\ChNameLowerCase{\LCNtrue\UCNfalse} +\def\ChNameUpperCase{\UCNtrue\LCNfalse} +\def\ChNameAsIs{\UCNfalse\LCNfalse} + +%%%%% Fix for AMSBook 971008 + +\@ifundefined{@chapapp}{\let\@chapapp\chaptername}{} + + +%%%%% Fix for Bjarne and appendix 980211 + +\newif\ifinapp +\inappfalse +\renewcommand\appendix{\par + \setcounter{chapter}{0}% + \setcounter{section}{0}% + \inapptrue% + \renewcommand\@chapapp{\appendixname}% + \renewcommand\thechapter{\@Alph\c@chapter}} + +%%%%% Fix for frontmatter, mainmatter, and backmatter 040920 + +\@ifundefined{@mainmatter}{\newif\if@mainmatter \@mainmattertrue}{} + +%%%%% + + + +\newcommand{\FmN}[1]{% +\ifUCN + {\MakeUppercase{#1}}\LCNfalse +\else + \ifLCN + {\MakeLowercase{#1}}\UCNfalse + \else #1 + \fi +\fi} + + +%%%% DEFINITION OF Title variables +\newcommand{\CTV}{\Huge\bfseries} +\newcommand{\ChTitleVar}[1]{\renewcommand{\CTV}{#1}} + +%%%% DEFINITION OF the basic rule width +\newlength{\RW} +\setlength{\RW}{1pt} +\newcommand{\ChRuleWidth}[1]{\setlength{\RW}{#1}} + +\newif\ifUCT +\UCTfalse +\newif\ifLCT +\LCTfalse +\def\ChTitleLowerCase{\LCTtrue\UCTfalse} +\def\ChTitleUpperCase{\UCTtrue\LCTfalse} +\def\ChTitleAsIs{\UCTfalse\LCTfalse} +\newcommand{\FmTi}[1]{% +\ifUCT + {\MakeUppercase{#1}}\LCTfalse +\else + \ifLCT + {\MakeLowercase{#1}}\UCTfalse + \else {#1} + \fi +\fi} + + + +\newlength{\mylen} +\newlength{\myhi} +\newlength{\px} +\newlength{\py} +\newlength{\pyy} +\newlength{\pxx} + + +\def\mghrulefill#1{\leavevmode\leaders\hrule\@height #1\hfill\kern\z@} + +\newcommand{\DOCH}{% + \CNV\FmN{\@chapapp}\space \CNoV\thechapter + \par\nobreak + \vskip 20\p@ + } +\newcommand{\DOTI}[1]{% + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@ + } +\newcommand{\DOTIS}[1]{% + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@ + } + +%%%%%% SONNY DEF + +\DeclareOption{Sonny}{% + \ChNameVar{\Large\sf} + \ChNumVar{\Huge} + \ChTitleVar{\Large\sf} + \ChRuleWidth{0.5pt} + \ChNameUpperCase + \renewcommand{\DOCH}{% + \raggedleft + \CNV\FmN{\@chapapp}\space \CNoV\thechapter + \par\nobreak + \vskip 40\p@} + \renewcommand{\DOTI}[1]{% + \CTV\raggedleft\mghrulefill{\RW}\par\nobreak + \vskip 5\p@ + \CTV\FmTi{#1}\par\nobreak + \mghrulefill{\RW}\par\nobreak + \vskip 40\p@} + \renewcommand{\DOTIS}[1]{% + \CTV\raggedleft\mghrulefill{\RW}\par\nobreak + \vskip 5\p@ + \CTV\FmTi{#1}\par\nobreak + \mghrulefill{\RW}\par\nobreak + \vskip 40\p@} +} + +%%%%%% LENNY DEF + +\DeclareOption{Lenny}{% + + \ChNameVar{\fontsize{14}{16}\usefont{OT1}{phv}{m}{n}\selectfont} + \ChNumVar{\fontsize{60}{62}\usefont{OT1}{ptm}{m}{n}\selectfont} + \ChTitleVar{\Huge\bfseries\rm} + \ChRuleWidth{1pt} + \renewcommand{\DOCH}{% + \settowidth{\px}{\CNV\FmN{\@chapapp}} + \addtolength{\px}{2pt} + \settoheight{\py}{\CNV\FmN{\@chapapp}} + \addtolength{\py}{1pt} + + \settowidth{\mylen}{\CNV\FmN{\@chapapp}\space\CNoV\thechapter} + \addtolength{\mylen}{1pt} + \settowidth{\pxx}{\CNoV\thechapter} + \addtolength{\pxx}{-1pt} + + \settoheight{\pyy}{\CNoV\thechapter} + \addtolength{\pyy}{-2pt} + \setlength{\myhi}{\pyy} + \addtolength{\myhi}{-1\py} + \par + \parbox[b]{\textwidth}{% + \rule[\py]{\RW}{\myhi}% + \hskip -\RW% + \rule[\pyy]{\px}{\RW}% + \hskip -\px% + \raggedright% + \CNV\FmN{\@chapapp}\space\CNoV\thechapter% + \hskip1pt% + \mghrulefill{\RW}% + \rule{\RW}{\pyy}\par\nobreak% + \vskip -\baselineskip% + \vskip -\pyy% + \hskip \mylen% + \mghrulefill{\RW}\par\nobreak% + \vskip \pyy}% + \vskip 20\p@} + + + \renewcommand{\DOTI}[1]{% + \raggedright + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + + \renewcommand{\DOTIS}[1]{% + \raggedright + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + } + +%%%%%% Peter Osbornes' version of LENNY DEF + +\DeclareOption{PetersLenny}{% + +% five new lengths +\newlength{\bl} % bottom left : orig \space +\setlength{\bl}{6pt} +\newcommand{\BL}[1]{\setlength{\bl}{#1}} +\newlength{\br} % bottom right : orig 1pt +\setlength{\br}{1pt} +\newcommand{\BR}[1]{\setlength{\br}{#1}} +\newlength{\tl} % top left : orig 2pt +\setlength{\tl}{2pt} +\newcommand{\TL}[1]{\setlength{\tl}{#1}} +\newlength{\trr} % top right :orig 1pt +\setlength{\trr}{1pt} +\newcommand{\TR}[1]{\setlength{\trr}{#1}} +\newlength{\blrule} % top right :orig 1pt +\setlength{\trr}{0pt} +\newcommand{\BLrule}[1]{\setlength{\blrule}{#1}} + + + \ChNameVar{\fontsize{14}{16}\usefont{OT1}{phv}{m}{n}\selectfont} + \ChNumVar{\fontsize{60}{62}\usefont{OT1}{ptm}{m}{n}\selectfont} + \ChTitleVar{\Huge\bfseries\rm} + \ChRuleWidth{1pt} +\renewcommand{\DOCH}{% + + +%%%%%%% tweaks for 1--9 and A--Z +\ifcase\c@chapter\relax% +\or\BL{-3pt}\TL{-4pt}\BR{0pt}\TR{-6pt}%1 +\or\BL{0pt}\TL{-4pt}\BR{2pt}\TR{-4pt}%2 +\or\BL{0pt}\TL{-4pt}\BR{2pt}\TR{-4pt}%3 +\or\BL{0pt}\TL{5pt}\BR{2pt}\TR{-4pt}%4 +\or\BL{0pt}\TL{3pt}\BR{2pt}\TR{-4pt}%5 +\or\BL{-1pt}\TL{0pt}\BR{2pt}\TR{-2pt}%6 +\or\BL{0pt}\TL{-3pt}\BR{2pt}\TR{-2pt}%7 +\or\BL{0pt}\TL{-3pt}\BR{2pt}\TR{-2pt}%8 +\or\BL{0pt}\TL{-3pt}\BR{-4pt}\TR{-2pt}%9 +\or\BL{-3pt}\TL{-3pt}\BR{2pt}\TR{-7pt}%10 +\or\BL{-6pt}\TL{-6pt}\BR{0pt}\TR{-9pt}%11 +\or\BL{-6pt}\TL{-6pt}\BR{2pt}\TR{-7pt}%12 +\or\BL{-5pt}\TL{-5pt}\BR{0pt}\TR{-9pt}%13 +\or\BL{-6pt}\TL{-6pt}\BR{0pt}\TR{-9pt}%14 +\or\BL{-3pt}\TL{-3pt}\BR{3pt}\TR{-6pt}%15 +\or\BL{-3pt}\TL{-3pt}\BR{3pt}\TR{-6pt}%16 +\or\BL{-5pt}\TL{-3pt}\BR{-8pt}\TR{-6pt}%17 +\or\BL{-5pt}\TL{-5pt}\BR{0pt}\TR{-9pt}%18 +\or\BL{-3pt}\TL{-3pt}\BR{-6pt}\TR{-9pt}%19 +\or\BL{0pt}\TL{0pt}\BR{0pt}\TR{-5pt}%20 +\fi + +\ifinapp\ifcase\c@chapter\relax% +\or\BL{0pt}\TL{14pt}\BR{5pt}\TR{-19pt}%A +\or\BL{0pt}\TL{-5pt}\BR{-3pt}\TR{-8pt}%B +\or\BL{-3pt}\TL{-2pt}\BR{1pt}\TR{-6pt}\BLrule{0pt}%C +\or\BL{0pt}\TL{-5pt}\BR{-3pt}\TR{-8pt}\BLrule{0pt}%D +\or\BL{0pt}\TL{-5pt}\BR{2pt}\TR{-3pt}%E +\or\BL{0pt}\TL{-5pt}\BR{-10pt}\TR{-1pt}%F +\or\BL{-3pt}\TL{0pt}\BR{0pt}\TR{-7pt}%G +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}%H +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}%I +\or\BL{2pt}\TL{0pt}\BR{-3pt}\TR{1pt}%J +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}%K +\or\BL{0pt}\TL{-5pt}\BR{2pt}\TR{-19pt}%L +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}%M +\or\BL{0pt}\TL{-5pt}\BR{-2pt}\TR{-1pt}%N +\or\BL{-3pt}\TL{-2pt}\BR{-3pt}\TR{-11pt}%O +\or\BL{0pt}\TL{-5pt}\BR{-9pt}\TR{-3pt}%P +\or\BL{-3pt}\TL{-2pt}\BR{-3pt}\TR{-11pt}%Q +\or\BL{0pt}\TL{-5pt}\BR{4pt}\TR{-8pt}%R +\or\BL{-2pt}\TL{-2pt}\BR{-2pt}\TR{-7pt}%S +\or\BL{-3pt}\TL{0pt}\BR{-5pt}\TR{4pt}\BLrule{8pt}%T +\or\BL{-7pt}\TL{-11pt}\BR{-5pt}\TR{-7pt}\BLrule{0pt}%U +\or\BL{-14pt}\TL{-5pt}\BR{-14pt}\TR{-1pt}\BLrule{14pt}%V +\or\BL{-10pt}\TL{-9pt}\BR{-13pt}\TR{-3pt}\BLrule{7pt}%W +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}\BLrule{0pt}%X +\or\BL{-6pt}\TL{-4pt}\BR{-7pt}\TR{1pt}\BLrule{7pt}%Y +\or\BL{0pt}\TL{-5pt}\BR{3pt}\TR{-1pt}\BLrule{0pt}%Z +\fi\fi +%%%%%%% + \settowidth{\px}{\CNV\FmN{\@chapapp}} + \addtolength{\px}{\tl} %MOD change 2pt to \tl + \settoheight{\py}{\CNV\FmN{\@chapapp}} + \addtolength{\py}{1pt} + + \settowidth{\mylen}{\CNV\FmN{\@chapapp}\space\CNoV\thechapter} + \addtolength{\mylen}{\trr}% MOD change 1pt to \tr + \settowidth{\pxx}{\CNoV\thechapter} + \addtolength{\pxx}{-1pt} + + \settoheight{\pyy}{\CNoV\thechapter} + \addtolength{\pyy}{-2pt} + \setlength{\myhi}{\pyy} + \addtolength{\myhi}{-1\py} + \par + \parbox[b]{\textwidth}{% + \rule[\py]{\RW}{\myhi}% + \hskip -\RW% + \rule[\pyy]{\px}{\RW}% + \hskip -\px% + \raggedright% + \CNV\FmN{\@chapapp}\rule{\blrule}{\RW}\hskip\bl\CNoV\thechapter%MOD +% \CNV\FmN{\@chapapp}\space\CNoV\thechapter %ORIGINAL + \hskip\br% %MOD 1pt to \br + \mghrulefill{\RW}% + \rule{\RW}{\pyy}\par\nobreak% + \vskip -\baselineskip% + \vskip -\pyy% + \hskip \mylen% + \mghrulefill{\RW}\par\nobreak% + \vskip \pyy}% + \vskip 20\p@} + + + \renewcommand{\DOTI}[1]{% + \raggedright + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + + \renewcommand{\DOTIS}[1]{% + \raggedright + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + } + + +% + + +%%%%%% BJORNSTRUP DEF + +\DeclareOption{Bjornstrup}{% + \usecolortrue + % pzc (Zapf Chancelery) is nice. ppl (Palatino) is cool too. + \ChNumVar{\fontsize{76}{80}\usefont{OT1}{pzc}{m}{n}\selectfont} + \ChTitleVar{\raggedleft\Large\sffamily\bfseries} + + \setlength{\myhi}{10pt} % Space between grey box border and text + \setlength{\mylen}{\textwidth} + \addtolength{\mylen}{-2\myhi} + \renewcommand{\DOCH}{% + \settowidth{\py}{\CNoV\thechapter} + \addtolength{\py}{-10pt} % Amount of space by which the +% % number is shifted right + \fboxsep=0pt% + \colorbox[gray]{.85}{\rule{0pt}{40pt}\parbox[b]{\textwidth}{\hfill}}% + \kern-\py\raise20pt% + \hbox{\color[gray]{.5}\CNoV\thechapter}\\% + } + + \renewcommand{\DOTI}[1]{% + \nointerlineskip\raggedright% + \fboxsep=\myhi% + \vskip-1ex% + \colorbox[gray]{.85}{\parbox[t]{\mylen}{\CTV\FmTi{#1}}}\par\nobreak% + \vskip 40\p@% + } + + \renewcommand{\DOTIS}[1]{% + \fboxsep=0pt + \colorbox[gray]{.85}{\rule{0pt}{40pt}\parbox[b]{\textwidth}{\hfill}}\\% + \nointerlineskip\raggedright% + \fboxsep=\myhi% + \colorbox[gray]{.85}{\parbox[t]{\mylen}{\CTV\FmTi{#1}}}\par\nobreak% + \vskip 40\p@% + } +} + + +%%%%%%% GLENN DEF + + +\DeclareOption{Glenn}{% + \ChNameVar{\bfseries\Large\sf} + \ChNumVar{\Huge} + \ChTitleVar{\bfseries\Large\rm} + \ChRuleWidth{1pt} + \ChNameUpperCase + \ChTitleUpperCase + \renewcommand{\DOCH}{% + \settoheight{\myhi}{\CTV\FmTi{Test}} + \setlength{\py}{\baselineskip} + \addtolength{\py}{\RW} + \addtolength{\py}{\myhi} + \setlength{\pyy}{\py} + \addtolength{\pyy}{-1\RW} + + \raggedright + \CNV\FmN{\@chapapp}\space\CNoV\thechapter + \hskip 3pt\mghrulefill{\RW}\rule[-1\pyy]{2\RW}{\py}\par\nobreak} + + \renewcommand{\DOTI}[1]{% + \addtolength{\pyy}{-4pt} + \settoheight{\myhi}{\CTV\FmTi{#1}} + \addtolength{\myhi}{\py} + \addtolength{\myhi}{-1\RW} + \vskip -1\pyy + \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt + \raggedleft\CTV\FmTi{#1}\par\nobreak + \vskip 80\p@} + +\newlength{\backskip} + \renewcommand{\DOTIS}[1]{% +% \setlength{\py}{10pt} +% \setlength{\pyy}{\py} +% \addtolength{\pyy}{\RW} +% \setlength{\myhi}{\baselineskip} +% \addtolength{\myhi}{\pyy} +% \mghrulefill{\RW}\rule[-1\py]{2\RW}{\pyy}\par\nobreak +% \addtolength{}{} +%\vskip -1\baselineskip +% \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 2pt +% \raggedleft\CTV\FmTi{#1}\par\nobreak +% \vskip 60\p@} +%% Fix suggested by Tomas Lundberg + \setlength{\py}{25pt} % eller vad man vill + \setlength{\pyy}{\py} + \setlength{\backskip}{\py} + \addtolength{\backskip}{2pt} + \addtolength{\pyy}{\RW} + \setlength{\myhi}{\baselineskip} + \addtolength{\myhi}{\pyy} + \mghrulefill{\RW}\rule[-1\py]{2\RW}{\pyy}\par\nobreak + \vskip -1\backskip + \rule{2\RW}{\myhi}\mghrulefill{\RW}\hskip 3pt % + \raggedleft\CTV\FmTi{#1}\par\nobreak + \vskip 40\p@} + } + +%%%%%%% CONNY DEF + +\DeclareOption{Conny}{% + \ChNameUpperCase + \ChTitleUpperCase + \ChNameVar{\centering\Huge\rm\bfseries} + \ChNumVar{\Huge} + \ChTitleVar{\centering\Huge\rm} + \ChRuleWidth{2pt} + + \renewcommand{\DOCH}{% + \mghrulefill{3\RW}\par\nobreak + \vskip -0.5\baselineskip + \mghrulefill{\RW}\par\nobreak + \CNV\FmN{\@chapapp}\space \CNoV\thechapter + \par\nobreak + \vskip -0.5\baselineskip + } + \renewcommand{\DOTI}[1]{% + \mghrulefill{\RW}\par\nobreak + \CTV\FmTi{#1}\par\nobreak + \vskip 60\p@ + } + \renewcommand{\DOTIS}[1]{% + \mghrulefill{\RW}\par\nobreak + \CTV\FmTi{#1}\par\nobreak + \vskip 60\p@ + } + } + +%%%%%%% REJNE DEF + +\DeclareOption{Rejne}{% + + \ChNameUpperCase + \ChTitleUpperCase + \ChNameVar{\centering\Large\rm} + \ChNumVar{\Huge} + \ChTitleVar{\centering\Huge\rm} + \ChRuleWidth{1pt} + \renewcommand{\DOCH}{% + \settoheight{\py}{\CNoV\thechapter} + \parskip=0pt plus 1pt % Set parskip to default, just in case v1.31 + \addtolength{\py}{-1pt} + \CNV\FmN{\@chapapp}\par\nobreak + \vskip 20\p@ + \setlength{\myhi}{2\baselineskip} + \setlength{\px}{\myhi} + \addtolength{\px}{-1\RW} + \rule[-1\px]{\RW}{\myhi}\mghrulefill{\RW}\hskip + 10pt\raisebox{-0.5\py}{\CNoV\thechapter}\hskip 10pt\mghrulefill{\RW}\rule[-1\px]{\RW}{\myhi}\par\nobreak + \vskip -3\p@% Added -2pt vskip to correct for streched text v1.31 + } + \renewcommand{\DOTI}[1]{% + \setlength{\mylen}{\textwidth} + \parskip=0pt plus 1pt % Set parskip to default, just in case v1.31 + \addtolength{\mylen}{-2\RW} + {\vrule width\RW}\parbox{\mylen}{\CTV\FmTi{#1}}{\vrule width\RW}\par\nobreak% + \vskip -3pt\rule{\RW}{2\baselineskip}\mghrulefill{\RW}\rule{\RW}{2\baselineskip}% + \vskip 60\p@% Added -2pt in vskip to correct for streched text v1.31 + } + \renewcommand{\DOTIS}[1]{% + \setlength{\py}{\fboxrule} + \setlength{\fboxrule}{\RW} + \setlength{\mylen}{\textwidth} + \addtolength{\mylen}{-2\RW} + \fbox{\parbox{\mylen}{\vskip 2\baselineskip\CTV\FmTi{#1}\par\nobreak\vskip \baselineskip}} + \setlength{\fboxrule}{\py} + \vskip 60\p@ + } + } + + +%%%%%%% BJARNE DEF + +\DeclareOption{Bjarne}{% + \ChNameUpperCase + \ChTitleUpperCase + \ChNameVar{\raggedleft\normalsize\rm} + \ChNumVar{\raggedleft \bfseries\Large} + \ChTitleVar{\raggedleft \Large\rm} + \ChRuleWidth{1pt} + + +%% Note thechapter -> c@chapter fix appendix bug +%% Fixed misspelled 12 + + \newcounter{AlphaCnt} + \newcounter{AlphaDecCnt} + \newcommand{\AlphaNo}{% + \ifcase\number\theAlphaCnt + \ifnum\c@chapter=0 + ZERO\else{}\fi + \or ONE\or TWO\or THREE\or FOUR\or FIVE + \or SIX\or SEVEN\or EIGHT\or NINE\or TEN + \or ELEVEN\or TWELVE\or THIRTEEN\or FOURTEEN\or FIFTEEN + \or SIXTEEN\or SEVENTEEN\or EIGHTEEN\or NINETEEN\fi +} + + \newcommand{\AlphaDecNo}{% + \setcounter{AlphaDecCnt}{0} + \@whilenum\number\theAlphaCnt>0\do + {\addtocounter{AlphaCnt}{-10} + \addtocounter{AlphaDecCnt}{1}} + \ifnum\number\theAlphaCnt=0 + \else + \addtocounter{AlphaDecCnt}{-1} + \addtocounter{AlphaCnt}{10} + \fi + + + \ifcase\number\theAlphaDecCnt\or TEN\or TWENTY\or THIRTY\or + FORTY\or FIFTY\or SIXTY\or SEVENTY\or EIGHTY\or NINETY\fi + } + \newcommand{\TheAlphaChapter}{% + + \ifinapp + \thechapter + \else + \setcounter{AlphaCnt}{\c@chapter} + \ifnum\c@chapter<20 + \AlphaNo + \else + \AlphaDecNo\AlphaNo + \fi + \fi + } + \renewcommand{\DOCH}{% + \mghrulefill{\RW}\par\nobreak + \CNV\FmN{\@chapapp}\par\nobreak + \CNoV\TheAlphaChapter\par\nobreak + \vskip -1\baselineskip\vskip 5pt\mghrulefill{\RW}\par\nobreak + \vskip 20\p@ + } + \renewcommand{\DOTI}[1]{% + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@ + } + \renewcommand{\DOTIS}[1]{% + \CTV\FmTi{#1}\par\nobreak + \vskip 40\p@ + } +} + +\DeclareOption*{% + \PackageWarning{fancychapter}{unknown style option} + } + +\ProcessOptions* \relax + +\ifusecolor + \RequirePackage{color} +\fi +\def\@makechapterhead#1{% + \vspace*{50\p@}% + {\parindent \z@ \raggedright \normalfont + \ifnum \c@secnumdepth >\m@ne + \if@mainmatter%%%%% Fix for frontmatter, mainmatter, and backmatter 040920 + \DOCH + \fi + \fi + \interlinepenalty\@M + \if@mainmatter%%%%% Fix for frontmatter, mainmatter, and backmatter 060424 + \DOTI{#1}% + \else% + \DOTIS{#1}% + \fi + }} + + +%%% Begin: To avoid problem with scrbook.cls (fncychap version 1.32) + +%%OUT: +%\def\@schapter#1{\if@twocolumn +% \@topnewpage[\@makeschapterhead{#1}]% +% \else +% \@makeschapterhead{#1}% +% \@afterheading +% \fi} + +%%IN: +\def\@schapter#1{% +\if@twocolumn% + \@makeschapterhead{#1}% +\else% + \@makeschapterhead{#1}% + \@afterheading% +\fi} + +%%% End: To avoid problem with scrbook.cls (fncychap version 1.32) + +\def\@makeschapterhead#1{% + \vspace*{50\p@}% + {\parindent \z@ \raggedright + \normalfont + \interlinepenalty\@M + \DOTIS{#1} + \vskip 40\p@ + }} + +\endinput + + diff --git a/doc/latex/manual.aux b/doc/latex/manual.aux new file mode 100644 index 0000000..4f41234 --- /dev/null +++ b/doc/latex/manual.aux @@ -0,0 +1,366 @@ +\relax +\ifx\hyper@anchor\@undefined +\global \let \oldcontentsline\contentsline +\gdef \contentsline#1#2#3#4{\oldcontentsline{#1}{#2}{#3}} +\global \let \oldnewlabel\newlabel +\gdef \newlabel#1#2{\newlabelxx{#1}#2} +\gdef \newlabelxx#1#2#3#4#5#6{\oldnewlabel{#1}{{#2}{#3}}} +\AtEndDocument{\let \contentsline\oldcontentsline +\let \newlabel\oldnewlabel} +\else +\global \let \hyper@last\relax +\fi + +\select@language{english} +\@writefile{toc}{\select@language{english}} +\@writefile{lof}{\select@language{english}} +\@writefile{lot}{\select@language{english}} +\newlabel{index::doc}{{}{1}{\relax }{section*.2}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {1}About S3QL}{1}{chapter.1}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{about:about-s3ql}{{1}{1}{About S3QL\relax }{chapter.1}{}} +\newlabel{about::doc}{{1}{1}{About S3QL\relax }{chapter.1}{}} +\newlabel{about:s3ql-user-s-guide}{{1}{1}{About S3QL\relax }{chapter.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {1.1}Features}{1}{section.1.1}} +\newlabel{about:features}{{1.1}{1}{Features\relax }{section.1.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {1.2}Development Status}{2}{section.1.2}} +\newlabel{about:development-status}{{1.2}{2}{Development Status\relax }{section.1.2}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {2}Installation}{3}{chapter.2}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{installation:installation}{{2}{3}{Installation\relax }{chapter.2}{}} +\newlabel{installation::doc}{{2}{3}{Installation\relax }{chapter.2}{}} +\@writefile{toc}{\contentsline {section}{\numberline {2.1}Dependencies}{3}{section.2.1}} +\newlabel{installation:dependencies}{{2.1}{3}{Dependencies\relax }{section.2.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {2.2}Installing S3QL}{4}{section.2.2}} +\newlabel{installation:inst-s3ql}{{2.2}{4}{Installing S3QL\relax }{section.2.2}{}} +\newlabel{installation:installing-s3ql}{{2.2}{4}{Installing S3QL\relax }{section.2.2}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {3}Storage Backends}{5}{chapter.3}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{backends::doc}{{3}{5}{Storage Backends\relax }{chapter.3}{}} +\newlabel{backends:storage-backends}{{3}{5}{Storage Backends\relax }{chapter.3}{}} +\@writefile{toc}{\contentsline {section}{\numberline {3.1}On Backend Reliability}{5}{section.3.1}} +\newlabel{backends:on-backend-reliability}{{3.1}{5}{On Backend Reliability\relax }{section.3.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {3.2}The \texttt {authinfo} file}{6}{section.3.2}} +\newlabel{backends:the-authinfo-file}{{3.2}{6}{The \texttt {authinfo} file\relax }{section.3.2}{}} +\@writefile{toc}{\contentsline {section}{\numberline {3.3}Consistency Guarantees}{6}{section.3.3}} +\newlabel{backends:consistency-guarantees}{{3.3}{6}{Consistency Guarantees\relax }{section.3.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {3.3.1}Dealing with Eventual Consistency}{6}{subsection.3.3.1}} +\newlabel{backends:dealing-with-eventual-consistency}{{3.3.1}{6}{Dealing with Eventual Consistency\relax }{subsection.3.3.1}{}} +\newlabel{backends:eventual-consistency}{{3.3.1}{6}{Dealing with Eventual Consistency\relax }{subsection.3.3.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {3.4}The Amazon S3 Backend}{7}{section.3.4}} +\newlabel{backends:the-amazon-s3-backend}{{3.4}{7}{The Amazon S3 Backend\relax }{section.3.4}{}} +\@writefile{toc}{\contentsline {section}{\numberline {3.5}The Local Backend}{8}{section.3.5}} +\newlabel{backends:the-local-backend}{{3.5}{8}{The Local Backend\relax }{section.3.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {3.6}The SFTP Backend}{8}{section.3.6}} +\newlabel{backends:the-sftp-backend}{{3.6}{8}{The SFTP Backend\relax }{section.3.6}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {4}File System Creation}{9}{chapter.4}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{mkfs::doc}{{4}{9}{File System Creation\relax }{chapter.4}{}} +\newlabel{mkfs:file-system-creation}{{4}{9}{File System Creation\relax }{chapter.4}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {5}Managing Buckets}{11}{chapter.5}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{adm::doc}{{5}{11}{Managing Buckets\relax }{chapter.5}{}} +\newlabel{adm:managing-buckets}{{5}{11}{Managing Buckets\relax }{chapter.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {5.1}Changing the Passphrase}{11}{section.5.1}} +\newlabel{adm:changing-the-passphrase}{{5.1}{11}{Changing the Passphrase\relax }{section.5.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {5.2}Upgrading the file system}{11}{section.5.2}} +\newlabel{adm:upgrading-the-file-system}{{5.2}{11}{Upgrading the file system\relax }{section.5.2}{}} +\@writefile{toc}{\contentsline {section}{\numberline {5.3}Deleting a file system}{12}{section.5.3}} +\newlabel{adm:deleting-a-file-system}{{5.3}{12}{Deleting a file system\relax }{section.5.3}{}} +\@writefile{toc}{\contentsline {section}{\numberline {5.4}Restoring Metadata Backups}{12}{section.5.4}} +\newlabel{adm:restoring-metadata-backups}{{5.4}{12}{Restoring Metadata Backups\relax }{section.5.4}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {6}Mounting}{13}{chapter.6}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{mount:mounting}{{6}{13}{Mounting\relax }{chapter.6}{}} +\newlabel{mount::doc}{{6}{13}{Mounting\relax }{chapter.6}{}} +\@writefile{toc}{\contentsline {section}{\numberline {6.1}Storing Encryption Passwords}{14}{section.6.1}} +\newlabel{mount:bucket-pw}{{6.1}{14}{Storing Encryption Passwords\relax }{section.6.1}{}} +\newlabel{mount:storing-encryption-passwords}{{6.1}{14}{Storing Encryption Passwords\relax }{section.6.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {6.2}Compression Algorithms}{14}{section.6.2}} +\newlabel{mount:compression-algorithms}{{6.2}{14}{Compression Algorithms\relax }{section.6.2}{}} +\@writefile{toc}{\contentsline {section}{\numberline {6.3}Parallel Compression}{15}{section.6.3}} +\newlabel{mount:parallel-compression}{{6.3}{15}{Parallel Compression\relax }{section.6.3}{}} +\@writefile{toc}{\contentsline {section}{\numberline {6.4}Notes about Caching}{15}{section.6.4}} +\newlabel{mount:notes-about-caching}{{6.4}{15}{Notes about Caching\relax }{section.6.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {6.4.1}Maximum Number of Cache Entries}{15}{subsection.6.4.1}} +\newlabel{mount:maximum-number-of-cache-entries}{{6.4.1}{15}{Maximum Number of Cache Entries\relax }{subsection.6.4.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {6.4.2}Cache Flushing and Expiration}{15}{subsection.6.4.2}} +\newlabel{mount:cache-flushing-and-expiration}{{6.4.2}{15}{Cache Flushing and Expiration\relax }{subsection.6.4.2}{}} +\@writefile{toc}{\contentsline {section}{\numberline {6.5}Automatic Mounting}{15}{section.6.5}} +\newlabel{mount:automatic-mounting}{{6.5}{15}{Automatic Mounting\relax }{section.6.5}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {7}Advanced S3QL Features}{17}{chapter.7}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{special:advanced-s3ql-features}{{7}{17}{Advanced S3QL Features\relax }{chapter.7}{}} +\newlabel{special::doc}{{7}{17}{Advanced S3QL Features\relax }{chapter.7}{}} +\@writefile{toc}{\contentsline {section}{\numberline {7.1}Snapshotting and Copy-on-Write}{17}{section.7.1}} +\newlabel{special:snapshotting-and-copy-on-write}{{7.1}{17}{Snapshotting and Copy-on-Write\relax }{section.7.1}{}} +\newlabel{special:s3qlcp}{{7.1}{17}{Snapshotting and Copy-on-Write\relax }{section.7.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {7.1.1}Snapshotting vs Hardlinking}{17}{subsection.7.1.1}} +\newlabel{special:snapshotting-vs-hardlinking}{{7.1.1}{17}{Snapshotting vs Hardlinking\relax }{subsection.7.1.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {7.2}Getting Statistics}{18}{section.7.2}} +\newlabel{special:s3qlstat}{{7.2}{18}{Getting Statistics\relax }{section.7.2}{}} +\newlabel{special:getting-statistics}{{7.2}{18}{Getting Statistics\relax }{section.7.2}{}} +\@writefile{toc}{\contentsline {section}{\numberline {7.3}Immutable Trees}{18}{section.7.3}} +\newlabel{special:immutable-trees}{{7.3}{18}{Immutable Trees\relax }{section.7.3}{}} +\newlabel{special:s3qllock}{{7.3}{18}{Immutable Trees\relax }{section.7.3}{}} +\@writefile{toc}{\contentsline {section}{\numberline {7.4}Fast Recursive Removal}{19}{section.7.4}} +\newlabel{special:s3qlrm}{{7.4}{19}{Fast Recursive Removal\relax }{section.7.4}{}} +\newlabel{special:fast-recursive-removal}{{7.4}{19}{Fast Recursive Removal\relax }{section.7.4}{}} +\@writefile{toc}{\contentsline {section}{\numberline {7.5}Runtime Configuration}{19}{section.7.5}} +\newlabel{special:runtime-configuration}{{7.5}{19}{Runtime Configuration\relax }{section.7.5}{}} +\newlabel{special:s3qlctrl}{{7.5}{19}{Runtime Configuration\relax }{section.7.5}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {8}Unmounting}{21}{chapter.8}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{umount::doc}{{8}{21}{Unmounting\relax }{chapter.8}{}} +\newlabel{umount:unmounting}{{8}{21}{Unmounting\relax }{chapter.8}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {9}Checking for Errors}{23}{chapter.9}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{fsck:checking-for-errors}{{9}{23}{Checking for Errors\relax }{chapter.9}{}} +\newlabel{fsck::doc}{{9}{23}{Checking for Errors\relax }{chapter.9}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {10}Contributed Programs}{25}{chapter.10}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{contrib:contributed-programs}{{10}{25}{Contributed Programs\relax }{chapter.10}{}} +\newlabel{contrib::doc}{{10}{25}{Contributed Programs\relax }{chapter.10}{}} +\@writefile{toc}{\contentsline {section}{\numberline {10.1}benchmark.py}{25}{section.10.1}} +\newlabel{contrib:benchmark-py}{{10.1}{25}{benchmark.py\relax }{section.10.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {10.2}s3\_copy.py}{25}{section.10.2}} +\newlabel{contrib:s3-copy-py}{{10.2}{25}{s3\_copy.py\relax }{section.10.2}{}} +\@writefile{toc}{\contentsline {section}{\numberline {10.3}pcp.py}{25}{section.10.3}} +\newlabel{contrib:pcp-py}{{10.3}{25}{pcp.py\relax }{section.10.3}{}} +\newlabel{contrib:pcp}{{10.3}{25}{pcp.py\relax }{section.10.3}{}} +\@writefile{toc}{\contentsline {section}{\numberline {10.4}s3\_backup.sh}{25}{section.10.4}} +\newlabel{contrib:s3-backup-sh}{{10.4}{25}{s3\_backup.sh\relax }{section.10.4}{}} +\@writefile{toc}{\contentsline {section}{\numberline {10.5}expire\_backups.py}{26}{section.10.5}} +\newlabel{contrib:expire-backups-py}{{10.5}{26}{expire\_backups.py\relax }{section.10.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {10.6}s3ql.conf}{27}{section.10.6}} +\newlabel{contrib:s3ql-conf}{{10.6}{27}{s3ql.conf\relax }{section.10.6}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {11}Tips \& Tricks}{29}{chapter.11}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{tips:tips-tricks}{{11}{29}{Tips \& Tricks\relax }{chapter.11}{}} +\newlabel{tips::doc}{{11}{29}{Tips \& Tricks\relax }{chapter.11}{}} +\@writefile{toc}{\contentsline {section}{\numberline {11.1}Permanently mounted backup file system}{29}{section.11.1}} +\newlabel{tips:copy-performance}{{11.1}{29}{Permanently mounted backup file system\relax }{section.11.1}{}} +\newlabel{tips:permanently-mounted-backup-file-system}{{11.1}{29}{Permanently mounted backup file system\relax }{section.11.1}{}} +\@writefile{toc}{\contentsline {section}{\numberline {11.2}Improving copy performance}{29}{section.11.2}} +\newlabel{tips:improving-copy-performance}{{11.2}{29}{Improving copy performance\relax }{section.11.2}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {12}Known Issues}{31}{chapter.12}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{issues:known-issues}{{12}{31}{Known Issues\relax }{chapter.12}{}} +\newlabel{issues::doc}{{12}{31}{Known Issues\relax }{chapter.12}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {13}Manpages}{33}{chapter.13}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{man/index:manpages}{{13}{33}{Manpages\relax }{chapter.13}{}} +\newlabel{man/index::doc}{{13}{33}{Manpages\relax }{chapter.13}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.1}The \textbf {mkfs.s3ql} command}{33}{section.13.1}} +\newlabel{man/mkfs:the-mkfs-s3ql-command}{{13.1}{33}{The \textbf {mkfs.s3ql} command\relax }{section.13.1}{}} +\newlabel{man/mkfs::doc}{{13.1}{33}{The \textbf {mkfs.s3ql} command\relax }{section.13.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.1.1}Synopsis}{33}{subsection.13.1.1}} +\newlabel{man/mkfs:synopsis}{{13.1.1}{33}{Synopsis\relax }{subsection.13.1.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.1.2}Description}{33}{subsection.13.1.2}} +\newlabel{man/mkfs:description}{{13.1.2}{33}{Description\relax }{subsection.13.1.2}{}} +\@writefile{toc}{\contentsline {subsubsection}{Amazon S3}{33}{subsubsection*.3}} +\newlabel{man/mkfs:amazon-s3}{{13.1.2}{33}{Amazon S3\relax }{subsubsection*.3}{}} +\@writefile{toc}{\contentsline {subsubsection}{Local}{33}{subsubsection*.4}} +\newlabel{man/mkfs:local}{{13.1.2}{33}{Local\relax }{subsubsection*.4}{}} +\@writefile{toc}{\contentsline {subsubsection}{SFTP}{33}{subsubsection*.5}} +\newlabel{man/mkfs:sftp}{{13.1.2}{33}{SFTP\relax }{subsubsection*.5}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.1.3}Options}{34}{subsection.13.1.3}} +\newlabel{man/mkfs:options}{{13.1.3}{34}{Options\relax }{subsection.13.1.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.1.4}Files}{34}{subsection.13.1.4}} +\newlabel{man/mkfs:files}{{13.1.4}{34}{Files\relax }{subsection.13.1.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.1.5}Exit Status}{34}{subsection.13.1.5}} +\newlabel{man/mkfs:exit-status}{{13.1.5}{34}{Exit Status\relax }{subsection.13.1.5}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.1.6}See Also}{34}{subsection.13.1.6}} +\newlabel{man/mkfs:see-also}{{13.1.6}{34}{See Also\relax }{subsection.13.1.6}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.2}The \textbf {s3qladm} command}{34}{section.13.2}} +\newlabel{man/adm::doc}{{13.2}{34}{The \textbf {s3qladm} command\relax }{section.13.2}{}} +\newlabel{man/adm:the-s3qladm-command}{{13.2}{34}{The \textbf {s3qladm} command\relax }{section.13.2}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.2.1}Synopsis}{34}{subsection.13.2.1}} +\newlabel{man/adm:synopsis}{{13.2.1}{34}{Synopsis\relax }{subsection.13.2.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.2.2}Description}{35}{subsection.13.2.2}} +\newlabel{man/adm:description}{{13.2.2}{35}{Description\relax }{subsection.13.2.2}{}} +\@writefile{toc}{\contentsline {subsubsection}{Amazon S3}{35}{subsubsection*.6}} +\newlabel{man/adm:amazon-s3}{{13.2.2}{35}{Amazon S3\relax }{subsubsection*.6}{}} +\@writefile{toc}{\contentsline {subsubsection}{Local}{35}{subsubsection*.7}} +\newlabel{man/adm:local}{{13.2.2}{35}{Local\relax }{subsubsection*.7}{}} +\@writefile{toc}{\contentsline {subsubsection}{SFTP}{35}{subsubsection*.8}} +\newlabel{man/adm:sftp}{{13.2.2}{35}{SFTP\relax }{subsubsection*.8}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.2.3}Options}{35}{subsection.13.2.3}} +\newlabel{man/adm:options}{{13.2.3}{35}{Options\relax }{subsection.13.2.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.2.4}Actions}{35}{subsection.13.2.4}} +\newlabel{man/adm:actions}{{13.2.4}{35}{Actions\relax }{subsection.13.2.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.2.5}Files}{36}{subsection.13.2.5}} +\newlabel{man/adm:files}{{13.2.5}{36}{Files\relax }{subsection.13.2.5}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.2.6}Exit Status}{36}{subsection.13.2.6}} +\newlabel{man/adm:exit-status}{{13.2.6}{36}{Exit Status\relax }{subsection.13.2.6}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.2.7}See Also}{36}{subsection.13.2.7}} +\newlabel{man/adm:see-also}{{13.2.7}{36}{See Also\relax }{subsection.13.2.7}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.3}The \textbf {mount.s3ql} command}{36}{section.13.3}} +\newlabel{man/mount::doc}{{13.3}{36}{The \textbf {mount.s3ql} command\relax }{section.13.3}{}} +\newlabel{man/mount:the-mount-s3ql-command}{{13.3}{36}{The \textbf {mount.s3ql} command\relax }{section.13.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.3.1}Synopsis}{36}{subsection.13.3.1}} +\newlabel{man/mount:synopsis}{{13.3.1}{36}{Synopsis\relax }{subsection.13.3.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.3.2}Description}{36}{subsection.13.3.2}} +\newlabel{man/mount:description}{{13.3.2}{36}{Description\relax }{subsection.13.3.2}{}} +\@writefile{toc}{\contentsline {subsubsection}{Amazon S3}{36}{subsubsection*.9}} +\newlabel{man/mount:amazon-s3}{{13.3.2}{36}{Amazon S3\relax }{subsubsection*.9}{}} +\@writefile{toc}{\contentsline {subsubsection}{Local}{36}{subsubsection*.10}} +\newlabel{man/mount:local}{{13.3.2}{36}{Local\relax }{subsubsection*.10}{}} +\@writefile{toc}{\contentsline {subsubsection}{SFTP}{36}{subsubsection*.11}} +\newlabel{man/mount:sftp}{{13.3.2}{36}{SFTP\relax }{subsubsection*.11}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.3.3}Options}{37}{subsection.13.3.3}} +\newlabel{man/mount:options}{{13.3.3}{37}{Options\relax }{subsection.13.3.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.3.4}Files}{38}{subsection.13.3.4}} +\newlabel{man/mount:files}{{13.3.4}{38}{Files\relax }{subsection.13.3.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.3.5}Exit Status}{38}{subsection.13.3.5}} +\newlabel{man/mount:exit-status}{{13.3.5}{38}{Exit Status\relax }{subsection.13.3.5}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.3.6}See Also}{38}{subsection.13.3.6}} +\newlabel{man/mount:see-also}{{13.3.6}{38}{See Also\relax }{subsection.13.3.6}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.4}The \textbf {s3qlstat} command}{38}{section.13.4}} +\newlabel{man/stat:the-s3qlstat-command}{{13.4}{38}{The \textbf {s3qlstat} command\relax }{section.13.4}{}} +\newlabel{man/stat::doc}{{13.4}{38}{The \textbf {s3qlstat} command\relax }{section.13.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.4.1}Synopsis}{38}{subsection.13.4.1}} +\newlabel{man/stat:synopsis}{{13.4.1}{38}{Synopsis\relax }{subsection.13.4.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.4.2}Description}{38}{subsection.13.4.2}} +\newlabel{man/stat:description}{{13.4.2}{38}{Description\relax }{subsection.13.4.2}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.4.3}Options}{38}{subsection.13.4.3}} +\newlabel{man/stat:options}{{13.4.3}{38}{Options\relax }{subsection.13.4.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.4.4}Exit Status}{38}{subsection.13.4.4}} +\newlabel{man/stat:exit-status}{{13.4.4}{38}{Exit Status\relax }{subsection.13.4.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.4.5}See Also}{38}{subsection.13.4.5}} +\newlabel{man/stat:see-also}{{13.4.5}{38}{See Also\relax }{subsection.13.4.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.5}The \textbf {s3qlctrl} command}{39}{section.13.5}} +\newlabel{man/ctrl:the-s3qlctrl-command}{{13.5}{39}{The \textbf {s3qlctrl} command\relax }{section.13.5}{}} +\newlabel{man/ctrl::doc}{{13.5}{39}{The \textbf {s3qlctrl} command\relax }{section.13.5}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.5.1}Synopsis}{39}{subsection.13.5.1}} +\newlabel{man/ctrl:synopsis}{{13.5.1}{39}{Synopsis\relax }{subsection.13.5.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.5.2}Description}{39}{subsection.13.5.2}} +\newlabel{man/ctrl:description}{{13.5.2}{39}{Description\relax }{subsection.13.5.2}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.5.3}Options}{39}{subsection.13.5.3}} +\newlabel{man/ctrl:options}{{13.5.3}{39}{Options\relax }{subsection.13.5.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.5.4}Exit Status}{39}{subsection.13.5.4}} +\newlabel{man/ctrl:exit-status}{{13.5.4}{39}{Exit Status\relax }{subsection.13.5.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.5.5}See Also}{39}{subsection.13.5.5}} +\newlabel{man/ctrl:see-also}{{13.5.5}{39}{See Also\relax }{subsection.13.5.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.6}The \textbf {s3qlcp} command}{40}{section.13.6}} +\newlabel{man/cp:the-s3qlcp-command}{{13.6}{40}{The \textbf {s3qlcp} command\relax }{section.13.6}{}} +\newlabel{man/cp::doc}{{13.6}{40}{The \textbf {s3qlcp} command\relax }{section.13.6}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.6.1}Synopsis}{40}{subsection.13.6.1}} +\newlabel{man/cp:synopsis}{{13.6.1}{40}{Synopsis\relax }{subsection.13.6.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.6.2}Description}{40}{subsection.13.6.2}} +\newlabel{man/cp:description}{{13.6.2}{40}{Description\relax }{subsection.13.6.2}{}} +\@writefile{toc}{\contentsline {subsubsection}{Snapshotting vs Hardlinking}{40}{subsubsection*.12}} +\newlabel{man/cp:snapshotting-vs-hardlinking}{{13.6.2}{40}{Snapshotting vs Hardlinking\relax }{subsubsection*.12}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.6.3}Options}{40}{subsection.13.6.3}} +\newlabel{man/cp:options}{{13.6.3}{40}{Options\relax }{subsection.13.6.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.6.4}Exit Status}{41}{subsection.13.6.4}} +\newlabel{man/cp:exit-status}{{13.6.4}{41}{Exit Status\relax }{subsection.13.6.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.6.5}See Also}{41}{subsection.13.6.5}} +\newlabel{man/cp:see-also}{{13.6.5}{41}{See Also\relax }{subsection.13.6.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.7}The \textbf {s3qlrm} command}{41}{section.13.7}} +\newlabel{man/rm::doc}{{13.7}{41}{The \textbf {s3qlrm} command\relax }{section.13.7}{}} +\newlabel{man/rm:the-s3qlrm-command}{{13.7}{41}{The \textbf {s3qlrm} command\relax }{section.13.7}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.7.1}Synopsis}{41}{subsection.13.7.1}} +\newlabel{man/rm:synopsis}{{13.7.1}{41}{Synopsis\relax }{subsection.13.7.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.7.2}Description}{41}{subsection.13.7.2}} +\newlabel{man/rm:description}{{13.7.2}{41}{Description\relax }{subsection.13.7.2}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.7.3}Options}{41}{subsection.13.7.3}} +\newlabel{man/rm:options}{{13.7.3}{41}{Options\relax }{subsection.13.7.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.7.4}Exit Status}{41}{subsection.13.7.4}} +\newlabel{man/rm:exit-status}{{13.7.4}{41}{Exit Status\relax }{subsection.13.7.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.7.5}See Also}{41}{subsection.13.7.5}} +\newlabel{man/rm:see-also}{{13.7.5}{41}{See Also\relax }{subsection.13.7.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.8}The \textbf {s3qllock} command}{42}{section.13.8}} +\newlabel{man/lock:the-s3qllock-command}{{13.8}{42}{The \textbf {s3qllock} command\relax }{section.13.8}{}} +\newlabel{man/lock::doc}{{13.8}{42}{The \textbf {s3qllock} command\relax }{section.13.8}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.8.1}Synopsis}{42}{subsection.13.8.1}} +\newlabel{man/lock:synopsis}{{13.8.1}{42}{Synopsis\relax }{subsection.13.8.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.8.2}Description}{42}{subsection.13.8.2}} +\newlabel{man/lock:description}{{13.8.2}{42}{Description\relax }{subsection.13.8.2}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.8.3}Rationale}{42}{subsection.13.8.3}} +\newlabel{man/lock:rationale}{{13.8.3}{42}{Rationale\relax }{subsection.13.8.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.8.4}Options}{42}{subsection.13.8.4}} +\newlabel{man/lock:options}{{13.8.4}{42}{Options\relax }{subsection.13.8.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.8.5}Exit Status}{42}{subsection.13.8.5}} +\newlabel{man/lock:exit-status}{{13.8.5}{42}{Exit Status\relax }{subsection.13.8.5}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.8.6}See Also}{43}{subsection.13.8.6}} +\newlabel{man/lock:see-also}{{13.8.6}{43}{See Also\relax }{subsection.13.8.6}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.9}The \textbf {umount.s3ql} command}{43}{section.13.9}} +\newlabel{man/umount::doc}{{13.9}{43}{The \textbf {umount.s3ql} command\relax }{section.13.9}{}} +\newlabel{man/umount:the-umount-s3ql-command}{{13.9}{43}{The \textbf {umount.s3ql} command\relax }{section.13.9}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.9.1}Synopsis}{43}{subsection.13.9.1}} +\newlabel{man/umount:synopsis}{{13.9.1}{43}{Synopsis\relax }{subsection.13.9.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.9.2}Description}{43}{subsection.13.9.2}} +\newlabel{man/umount:description}{{13.9.2}{43}{Description\relax }{subsection.13.9.2}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.9.3}Options}{43}{subsection.13.9.3}} +\newlabel{man/umount:options}{{13.9.3}{43}{Options\relax }{subsection.13.9.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.9.4}Exit Status}{43}{subsection.13.9.4}} +\newlabel{man/umount:exit-status}{{13.9.4}{43}{Exit Status\relax }{subsection.13.9.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.9.5}See Also}{43}{subsection.13.9.5}} +\newlabel{man/umount:see-also}{{13.9.5}{43}{See Also\relax }{subsection.13.9.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.10}The \textbf {fsck.s3ql} command}{44}{section.13.10}} +\newlabel{man/fsck::doc}{{13.10}{44}{The \textbf {fsck.s3ql} command\relax }{section.13.10}{}} +\newlabel{man/fsck:the-fsck-s3ql-command}{{13.10}{44}{The \textbf {fsck.s3ql} command\relax }{section.13.10}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.10.1}Synopsis}{44}{subsection.13.10.1}} +\newlabel{man/fsck:synopsis}{{13.10.1}{44}{Synopsis\relax }{subsection.13.10.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.10.2}Description}{44}{subsection.13.10.2}} +\newlabel{man/fsck:description}{{13.10.2}{44}{Description\relax }{subsection.13.10.2}{}} +\@writefile{toc}{\contentsline {subsubsection}{Amazon S3}{44}{subsubsection*.13}} +\newlabel{man/fsck:amazon-s3}{{13.10.2}{44}{Amazon S3\relax }{subsubsection*.13}{}} +\@writefile{toc}{\contentsline {subsubsection}{Local}{44}{subsubsection*.14}} +\newlabel{man/fsck:local}{{13.10.2}{44}{Local\relax }{subsubsection*.14}{}} +\@writefile{toc}{\contentsline {subsubsection}{SFTP}{44}{subsubsection*.15}} +\newlabel{man/fsck:sftp}{{13.10.2}{44}{SFTP\relax }{subsubsection*.15}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.10.3}Options}{44}{subsection.13.10.3}} +\newlabel{man/fsck:options}{{13.10.3}{44}{Options\relax }{subsection.13.10.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.10.4}Files}{45}{subsection.13.10.4}} +\newlabel{man/fsck:files}{{13.10.4}{45}{Files\relax }{subsection.13.10.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.10.5}Exit Status}{45}{subsection.13.10.5}} +\newlabel{man/fsck:exit-status}{{13.10.5}{45}{Exit Status\relax }{subsection.13.10.5}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.10.6}See Also}{45}{subsection.13.10.6}} +\newlabel{man/fsck:see-also}{{13.10.6}{45}{See Also\relax }{subsection.13.10.6}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.11}The \textbf {pcp} command}{45}{section.13.11}} +\newlabel{man/pcp:the-pcp-command}{{13.11}{45}{The \textbf {pcp} command\relax }{section.13.11}{}} +\newlabel{man/pcp::doc}{{13.11}{45}{The \textbf {pcp} command\relax }{section.13.11}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.11.1}Synopsis}{45}{subsection.13.11.1}} +\newlabel{man/pcp:synopsis}{{13.11.1}{45}{Synopsis\relax }{subsection.13.11.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.11.2}Description}{45}{subsection.13.11.2}} +\newlabel{man/pcp:description}{{13.11.2}{45}{Description\relax }{subsection.13.11.2}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.11.3}Options}{45}{subsection.13.11.3}} +\newlabel{man/pcp:options}{{13.11.3}{45}{Options\relax }{subsection.13.11.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.11.4}Exit Status}{45}{subsection.13.11.4}} +\newlabel{man/pcp:exit-status}{{13.11.4}{45}{Exit Status\relax }{subsection.13.11.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.11.5}See Also}{45}{subsection.13.11.5}} +\newlabel{man/pcp:see-also}{{13.11.5}{45}{See Also\relax }{subsection.13.11.5}{}} +\@writefile{toc}{\contentsline {section}{\numberline {13.12}The \textbf {expire\_backups} command}{46}{section.13.12}} +\newlabel{man/expire_backups::doc}{{13.12}{46}{The \textbf {expire\_backups} command\relax }{section.13.12}{}} +\newlabel{man/expire_backups:the-expire-backups-command}{{13.12}{46}{The \textbf {expire\_backups} command\relax }{section.13.12}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.12.1}Synopsis}{46}{subsection.13.12.1}} +\newlabel{man/expire_backups:synopsis}{{13.12.1}{46}{Synopsis\relax }{subsection.13.12.1}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.12.2}Description}{46}{subsection.13.12.2}} +\newlabel{man/expire_backups:description}{{13.12.2}{46}{Description\relax }{subsection.13.12.2}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.12.3}Options}{47}{subsection.13.12.3}} +\newlabel{man/expire_backups:options}{{13.12.3}{47}{Options\relax }{subsection.13.12.3}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.12.4}Exit Status}{47}{subsection.13.12.4}} +\newlabel{man/expire_backups:exit-status}{{13.12.4}{47}{Exit Status\relax }{subsection.13.12.4}{}} +\@writefile{toc}{\contentsline {subsection}{\numberline {13.12.5}See Also}{47}{subsection.13.12.5}} +\newlabel{man/expire_backups:see-also}{{13.12.5}{47}{See Also\relax }{subsection.13.12.5}{}} +\@writefile{toc}{\contentsline {chapter}{\numberline {14}Further Resources / Getting Help}{49}{chapter.14}} +\@writefile{lof}{\addvspace {10\p@ }} +\@writefile{lot}{\addvspace {10\p@ }} +\newlabel{resources::doc}{{14}{49}{Further Resources / Getting Help\relax }{chapter.14}{}} +\newlabel{resources:further-resources-getting-help}{{14}{49}{Further Resources / Getting Help\relax }{chapter.14}{}} +\newlabel{resources:resources}{{14}{49}{Further Resources / Getting Help\relax }{chapter.14}{}} diff --git a/doc/latex/manual.idx b/doc/latex/manual.idx new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/doc/latex/manual.idx diff --git a/doc/latex/manual.log b/doc/latex/manual.log new file mode 100644 index 0000000..20029d7 --- /dev/null +++ b/doc/latex/manual.log @@ -0,0 +1,934 @@ +This is pdfTeX, Version 3.1415926-1.40.10 (TeX Live 2009/Debian) (format=pdflatex 2011.4.17) 20 MAY 2011 12:20 +entering extended mode + %&-line parsing enabled. +**manual.tex +(./manual.tex +LaTeX2e <2009/09/24> +Babel <v3.8l> and hyphenation patterns for english, usenglishmax, dumylang, noh +yphenation, ngerman, german, german-x-2009-06-19, ngerman-x-2009-06-19, loaded. + +(./sphinxmanual.cls +Document Class: sphinxmanual 2009/06/02 Document class (Sphinx manual) +(/usr/share/texmf-texlive/tex/latex/base/report.cls +Document Class: report 2007/10/19 v1.4h Standard LaTeX document class +(/usr/share/texmf-texlive/tex/latex/base/size10.clo +File: size10.clo 2007/10/19 v1.4h Standard LaTeX file (size option) +) +\c@part=\count79 +\c@chapter=\count80 +\c@section=\count81 +\c@subsection=\count82 +\c@subsubsection=\count83 +\c@paragraph=\count84 +\c@subparagraph=\count85 +\c@figure=\count86 +\c@table=\count87 +\abovecaptionskip=\skip41 +\belowcaptionskip=\skip42 +\bibindent=\dimen102 +)) (/usr/share/texmf-texlive/tex/latex/base/inputenc.sty +Package: inputenc 2008/03/30 v1.1d Input encoding file +\inpenc@prehook=\toks14 +\inpenc@posthook=\toks15 +(/usr/share/texmf-texlive/tex/latex/base/utf8.def +File: utf8.def 2008/04/05 v1.1m UTF-8 support for inputenc +Now handling font encoding OML ... +... no UTF-8 mapping file for font encoding OML +Now handling font encoding T1 ... +... processing UTF-8 mapping file for font encoding T1 +(/usr/share/texmf-texlive/tex/latex/base/t1enc.dfu +File: t1enc.dfu 2008/04/05 v1.1m UTF-8 support for inputenc + defining Unicode char U+00A1 (decimal 161) + defining Unicode char U+00A3 (decimal 163) + defining Unicode char U+00AB (decimal 171) + defining Unicode char U+00BB (decimal 187) + defining Unicode char U+00BF (decimal 191) + defining Unicode char U+00C0 (decimal 192) + defining Unicode char U+00C1 (decimal 193) + defining Unicode char U+00C2 (decimal 194) + defining Unicode char U+00C3 (decimal 195) + defining Unicode char U+00C4 (decimal 196) + defining Unicode char U+00C5 (decimal 197) + defining Unicode char U+00C6 (decimal 198) + defining Unicode char U+00C7 (decimal 199) + defining Unicode char U+00C8 (decimal 200) + defining Unicode char U+00C9 (decimal 201) + defining Unicode char U+00CA (decimal 202) + defining Unicode char U+00CB (decimal 203) + defining Unicode char U+00CC (decimal 204) + defining Unicode char U+00CD (decimal 205) + defining Unicode char U+00CE (decimal 206) + defining Unicode char U+00CF (decimal 207) + defining Unicode char U+00D0 (decimal 208) + defining Unicode char U+00D1 (decimal 209) + defining Unicode char U+00D2 (decimal 210) + defining Unicode char U+00D3 (decimal 211) + defining Unicode char U+00D4 (decimal 212) + defining Unicode char U+00D5 (decimal 213) + defining Unicode char U+00D6 (decimal 214) + defining Unicode char U+00D8 (decimal 216) + defining Unicode char U+00D9 (decimal 217) + defining Unicode char U+00DA (decimal 218) + defining Unicode char U+00DB (decimal 219) + defining Unicode char U+00DC (decimal 220) + defining Unicode char U+00DD (decimal 221) + defining Unicode char U+00DE (decimal 222) + defining Unicode char U+00DF (decimal 223) + defining Unicode char U+00E0 (decimal 224) + defining Unicode char U+00E1 (decimal 225) + defining Unicode char U+00E2 (decimal 226) + defining Unicode char U+00E3 (decimal 227) + defining Unicode char U+00E4 (decimal 228) + defining Unicode char U+00E5 (decimal 229) + defining Unicode char U+00E6 (decimal 230) + defining Unicode char U+00E7 (decimal 231) + defining Unicode char U+00E8 (decimal 232) + defining Unicode char U+00E9 (decimal 233) + defining Unicode char U+00EA (decimal 234) + defining Unicode char U+00EB (decimal 235) + defining Unicode char U+00EC (decimal 236) + defining Unicode char U+00ED (decimal 237) + defining Unicode char U+00EE (decimal 238) + defining Unicode char U+00EF (decimal 239) + defining Unicode char U+00F0 (decimal 240) + defining Unicode char U+00F1 (decimal 241) + defining Unicode char U+00F2 (decimal 242) + defining Unicode char U+00F3 (decimal 243) + defining Unicode char U+00F4 (decimal 244) + defining Unicode char U+00F5 (decimal 245) + defining Unicode char U+00F6 (decimal 246) + defining Unicode char U+00F8 (decimal 248) + defining Unicode char U+00F9 (decimal 249) + defining Unicode char U+00FA (decimal 250) + defining Unicode char U+00FB (decimal 251) + defining Unicode char U+00FC (decimal 252) + defining Unicode char U+00FD (decimal 253) + defining Unicode char U+00FE (decimal 254) + defining Unicode char U+00FF (decimal 255) + defining Unicode char U+0102 (decimal 258) + defining Unicode char U+0103 (decimal 259) + defining Unicode char U+0104 (decimal 260) + defining Unicode char U+0105 (decimal 261) + defining Unicode char U+0106 (decimal 262) + defining Unicode char U+0107 (decimal 263) + defining Unicode char U+010C (decimal 268) + defining Unicode char U+010D (decimal 269) + defining Unicode char U+010E (decimal 270) + defining Unicode char U+010F (decimal 271) + defining Unicode char U+0110 (decimal 272) + defining Unicode char U+0111 (decimal 273) + defining Unicode char U+0118 (decimal 280) + defining Unicode char U+0119 (decimal 281) + defining Unicode char U+011A (decimal 282) + defining Unicode char U+011B (decimal 283) + defining Unicode char U+011E (decimal 286) + defining Unicode char U+011F (decimal 287) + defining Unicode char U+0130 (decimal 304) + defining Unicode char U+0131 (decimal 305) + defining Unicode char U+0132 (decimal 306) + defining Unicode char U+0133 (decimal 307) + defining Unicode char U+0139 (decimal 313) + defining Unicode char U+013A (decimal 314) + defining Unicode char U+013D (decimal 317) + defining Unicode char U+013E (decimal 318) + defining Unicode char U+0141 (decimal 321) + defining Unicode char U+0142 (decimal 322) + defining Unicode char U+0143 (decimal 323) + defining Unicode char U+0144 (decimal 324) + defining Unicode char U+0147 (decimal 327) + defining Unicode char U+0148 (decimal 328) + defining Unicode char U+014A (decimal 330) + defining Unicode char U+014B (decimal 331) + defining Unicode char U+0150 (decimal 336) + defining Unicode char U+0151 (decimal 337) + defining Unicode char U+0152 (decimal 338) + defining Unicode char U+0153 (decimal 339) + defining Unicode char U+0154 (decimal 340) + defining Unicode char U+0155 (decimal 341) + defining Unicode char U+0158 (decimal 344) + defining Unicode char U+0159 (decimal 345) + defining Unicode char U+015A (decimal 346) + defining Unicode char U+015B (decimal 347) + defining Unicode char U+015E (decimal 350) + defining Unicode char U+015F (decimal 351) + defining Unicode char U+0160 (decimal 352) + defining Unicode char U+0161 (decimal 353) + defining Unicode char U+0162 (decimal 354) + defining Unicode char U+0163 (decimal 355) + defining Unicode char U+0164 (decimal 356) + defining Unicode char U+0165 (decimal 357) + defining Unicode char U+016E (decimal 366) + defining Unicode char U+016F (decimal 367) + defining Unicode char U+0170 (decimal 368) + defining Unicode char U+0171 (decimal 369) + defining Unicode char U+0178 (decimal 376) + defining Unicode char U+0179 (decimal 377) + defining Unicode char U+017A (decimal 378) + defining Unicode char U+017B (decimal 379) + defining Unicode char U+017C (decimal 380) + defining Unicode char U+017D (decimal 381) + defining Unicode char U+017E (decimal 382) + defining Unicode char U+200C (decimal 8204) + defining Unicode char U+2013 (decimal 8211) + defining Unicode char U+2014 (decimal 8212) + defining Unicode char U+2018 (decimal 8216) + defining Unicode char U+2019 (decimal 8217) + defining Unicode char U+201A (decimal 8218) + defining Unicode char U+201C (decimal 8220) + defining Unicode char U+201D (decimal 8221) + defining Unicode char U+201E (decimal 8222) + defining Unicode char U+2030 (decimal 8240) + defining Unicode char U+2031 (decimal 8241) + defining Unicode char U+2039 (decimal 8249) + defining Unicode char U+203A (decimal 8250) + defining Unicode char U+2423 (decimal 9251) +) +Now handling font encoding OT1 ... +... processing UTF-8 mapping file for font encoding OT1 +(/usr/share/texmf-texlive/tex/latex/base/ot1enc.dfu +File: ot1enc.dfu 2008/04/05 v1.1m UTF-8 support for inputenc + defining Unicode char U+00A1 (decimal 161) + defining Unicode char U+00A3 (decimal 163) + defining Unicode char U+00B8 (decimal 184) + defining Unicode char U+00BF (decimal 191) + defining Unicode char U+00C5 (decimal 197) + defining Unicode char U+00C6 (decimal 198) + defining Unicode char U+00D8 (decimal 216) + defining Unicode char U+00DF (decimal 223) + defining Unicode char U+00E6 (decimal 230) + defining Unicode char U+00EC (decimal 236) + defining Unicode char U+00ED (decimal 237) + defining Unicode char U+00EE (decimal 238) + defining Unicode char U+00EF (decimal 239) + defining Unicode char U+00F8 (decimal 248) + defining Unicode char U+0131 (decimal 305) + defining Unicode char U+0141 (decimal 321) + defining Unicode char U+0142 (decimal 322) + defining Unicode char U+0152 (decimal 338) + defining Unicode char U+0153 (decimal 339) + defining Unicode char U+2013 (decimal 8211) + defining Unicode char U+2014 (decimal 8212) + defining Unicode char U+2018 (decimal 8216) + defining Unicode char U+2019 (decimal 8217) + defining Unicode char U+201C (decimal 8220) + defining Unicode char U+201D (decimal 8221) +) +Now handling font encoding OMS ... +... processing UTF-8 mapping file for font encoding OMS +(/usr/share/texmf-texlive/tex/latex/base/omsenc.dfu +File: omsenc.dfu 2008/04/05 v1.1m UTF-8 support for inputenc + defining Unicode char U+00A7 (decimal 167) + defining Unicode char U+00B6 (decimal 182) + defining Unicode char U+00B7 (decimal 183) + defining Unicode char U+2020 (decimal 8224) + defining Unicode char U+2021 (decimal 8225) + defining Unicode char U+2022 (decimal 8226) +) +Now handling font encoding OMX ... +... no UTF-8 mapping file for font encoding OMX +Now handling font encoding U ... +... no UTF-8 mapping file for font encoding U + defining Unicode char U+00A9 (decimal 169) + defining Unicode char U+00AA (decimal 170) + defining Unicode char U+00AE (decimal 174) + defining Unicode char U+00BA (decimal 186) + defining Unicode char U+02C6 (decimal 710) + defining Unicode char U+02DC (decimal 732) + defining Unicode char U+200C (decimal 8204) + defining Unicode char U+2026 (decimal 8230) + defining Unicode char U+2122 (decimal 8482) + defining Unicode char U+2423 (decimal 9251) +)) + defining Unicode char U+00A0 (decimal 160) +(/usr/share/texmf-texlive/tex/latex/base/fontenc.sty +Package: fontenc 2005/09/27 v1.99g Standard LaTeX package +(/usr/share/texmf-texlive/tex/latex/base/t1enc.def +File: t1enc.def 2005/09/27 v1.99g Standard LaTeX file +LaTeX Font Info: Redeclaring font encoding T1 on input line 43. +)) (/usr/share/texmf-texlive/tex/generic/babel/babel.sty +Package: babel 2008/07/06 v3.8l The Babel package +(/usr/share/texmf-texlive/tex/generic/babel/english.ldf +Language: english 2005/03/30 v3.3o English support from the babel system +(/usr/share/texmf-texlive/tex/generic/babel/babel.def +File: babel.def 2008/07/06 v3.8l Babel common definitions +\babel@savecnt=\count88 +\U@D=\dimen103 +) +\l@british = a dialect from \language\l@english +\l@UKenglish = a dialect from \language\l@english +\l@canadian = a dialect from \language\l@american +\l@australian = a dialect from \language\l@british +\l@newzealand = a dialect from \language\l@british +)) (/usr/share/texmf-texlive/tex/latex/psnfss/times.sty +Package: times 2005/04/12 PSNFSS-v9.2a (SPQR) +) (./fncychap.sty +Package: fncychap 2007/07/30 v1.34 LaTeX package (Revised chapters) +\RW=\skip43 +\mylen=\skip44 +\myhi=\skip45 +\px=\skip46 +\py=\skip47 +\pyy=\skip48 +\pxx=\skip49 +\c@AlphaCnt=\count89 +\c@AlphaDecCnt=\count90 +) (/usr/share/texmf-texlive/tex/latex/tools/longtable.sty +Package: longtable 2004/02/01 v4.11 Multi-page Table package (DPC) +\LTleft=\skip50 +\LTright=\skip51 +\LTpre=\skip52 +\LTpost=\skip53 +\LTchunksize=\count91 +\LTcapwidth=\dimen104 +\LT@head=\box26 +\LT@firsthead=\box27 +\LT@foot=\box28 +\LT@lastfoot=\box29 +\LT@cols=\count92 +\LT@rows=\count93 +\c@LT@tables=\count94 +\c@LT@chunks=\count95 +\LT@p@ftn=\toks16 +) (./sphinx.sty +Package: sphinx 2010/01/15 LaTeX package (Sphinx markup) +(/usr/share/texmf-texlive/tex/latex/base/textcomp.sty +Package: textcomp 2005/09/27 v1.99g Standard LaTeX package +Package textcomp Info: Sub-encoding information: +(textcomp) 5 = only ISO-Adobe without \textcurrency +(textcomp) 4 = 5 + \texteuro +(textcomp) 3 = 4 + \textohm +(textcomp) 2 = 3 + \textestimated + \textcurrency +(textcomp) 1 = TS1 - \textcircled - \t +(textcomp) 0 = TS1 (full) +(textcomp) Font families with sub-encoding setting implement +(textcomp) only a restricted character set as indicated. +(textcomp) Family '?' is the default used for unknown fonts. +(textcomp) See the documentation for details. +Package textcomp Info: Setting ? sub-encoding to TS1/1 on input line 71. +(/usr/share/texmf-texlive/tex/latex/base/ts1enc.def +File: ts1enc.def 2001/06/05 v3.0e (jk/car/fm) Standard LaTeX file +Now handling font encoding TS1 ... +... processing UTF-8 mapping file for font encoding TS1 +(/usr/share/texmf-texlive/tex/latex/base/ts1enc.dfu +File: ts1enc.dfu 2008/04/05 v1.1m UTF-8 support for inputenc + defining Unicode char U+00A2 (decimal 162) + defining Unicode char U+00A3 (decimal 163) + defining Unicode char U+00A4 (decimal 164) + defining Unicode char U+00A5 (decimal 165) + defining Unicode char U+00A6 (decimal 166) + defining Unicode char U+00A7 (decimal 167) + defining Unicode char U+00A8 (decimal 168) + defining Unicode char U+00A9 (decimal 169) + defining Unicode char U+00AA (decimal 170) + defining Unicode char U+00AC (decimal 172) + defining Unicode char U+00AE (decimal 174) + defining Unicode char U+00AF (decimal 175) + defining Unicode char U+00B0 (decimal 176) + defining Unicode char U+00B1 (decimal 177) + defining Unicode char U+00B2 (decimal 178) + defining Unicode char U+00B3 (decimal 179) + defining Unicode char U+00B4 (decimal 180) + defining Unicode char U+00B5 (decimal 181) + defining Unicode char U+00B6 (decimal 182) + defining Unicode char U+00B7 (decimal 183) + defining Unicode char U+00B9 (decimal 185) + defining Unicode char U+00BA (decimal 186) + defining Unicode char U+00BC (decimal 188) + defining Unicode char U+00BD (decimal 189) + defining Unicode char U+00BE (decimal 190) + defining Unicode char U+00D7 (decimal 215) + defining Unicode char U+00F7 (decimal 247) + defining Unicode char U+0192 (decimal 402) + defining Unicode char U+02C7 (decimal 711) + defining Unicode char U+02D8 (decimal 728) + defining Unicode char U+02DD (decimal 733) + defining Unicode char U+0E3F (decimal 3647) + defining Unicode char U+2016 (decimal 8214) + defining Unicode char U+2020 (decimal 8224) + defining Unicode char U+2021 (decimal 8225) + defining Unicode char U+2022 (decimal 8226) + defining Unicode char U+2030 (decimal 8240) + defining Unicode char U+2031 (decimal 8241) + defining Unicode char U+203B (decimal 8251) + defining Unicode char U+203D (decimal 8253) + defining Unicode char U+2044 (decimal 8260) + defining Unicode char U+204E (decimal 8270) + defining Unicode char U+2052 (decimal 8274) + defining Unicode char U+20A1 (decimal 8353) + defining Unicode char U+20A4 (decimal 8356) + defining Unicode char U+20A6 (decimal 8358) + defining Unicode char U+20A9 (decimal 8361) + defining Unicode char U+20AB (decimal 8363) + defining Unicode char U+20AC (decimal 8364) + defining Unicode char U+20B1 (decimal 8369) + defining Unicode char U+2103 (decimal 8451) + defining Unicode char U+2116 (decimal 8470) + defining Unicode char U+2117 (decimal 8471) + defining Unicode char U+211E (decimal 8478) + defining Unicode char U+2120 (decimal 8480) + defining Unicode char U+2122 (decimal 8482) + defining Unicode char U+2126 (decimal 8486) + defining Unicode char U+2127 (decimal 8487) + defining Unicode char U+212E (decimal 8494) + defining Unicode char U+2190 (decimal 8592) + defining Unicode char U+2191 (decimal 8593) + defining Unicode char U+2192 (decimal 8594) + defining Unicode char U+2193 (decimal 8595) + defining Unicode char U+2329 (decimal 9001) + defining Unicode char U+232A (decimal 9002) + defining Unicode char U+2422 (decimal 9250) + defining Unicode char U+25E6 (decimal 9702) + defining Unicode char U+25EF (decimal 9711) + defining Unicode char U+266A (decimal 9834) +)) +LaTeX Info: Redefining \oldstylenums on input line 266. +Package textcomp Info: Setting cmr sub-encoding to TS1/0 on input line 281. +Package textcomp Info: Setting cmss sub-encoding to TS1/0 on input line 282. +Package textcomp Info: Setting cmtt sub-encoding to TS1/0 on input line 283. +Package textcomp Info: Setting cmvtt sub-encoding to TS1/0 on input line 284. +Package textcomp Info: Setting cmbr sub-encoding to TS1/0 on input line 285. +Package textcomp Info: Setting cmtl sub-encoding to TS1/0 on input line 286. +Package textcomp Info: Setting ccr sub-encoding to TS1/0 on input line 287. +Package textcomp Info: Setting ptm sub-encoding to TS1/4 on input line 288. +Package textcomp Info: Setting pcr sub-encoding to TS1/4 on input line 289. +Package textcomp Info: Setting phv sub-encoding to TS1/4 on input line 290. +Package textcomp Info: Setting ppl sub-encoding to TS1/3 on input line 291. +Package textcomp Info: Setting pag sub-encoding to TS1/4 on input line 292. +Package textcomp Info: Setting pbk sub-encoding to TS1/4 on input line 293. +Package textcomp Info: Setting pnc sub-encoding to TS1/4 on input line 294. +Package textcomp Info: Setting pzc sub-encoding to TS1/4 on input line 295. +Package textcomp Info: Setting bch sub-encoding to TS1/4 on input line 296. +Package textcomp Info: Setting put sub-encoding to TS1/5 on input line 297. +Package textcomp Info: Setting uag sub-encoding to TS1/5 on input line 298. +Package textcomp Info: Setting ugq sub-encoding to TS1/5 on input line 299. +Package textcomp Info: Setting ul8 sub-encoding to TS1/4 on input line 300. +Package textcomp Info: Setting ul9 sub-encoding to TS1/4 on input line 301. +Package textcomp Info: Setting augie sub-encoding to TS1/5 on input line 302. +Package textcomp Info: Setting dayrom sub-encoding to TS1/3 on input line 303. +Package textcomp Info: Setting dayroms sub-encoding to TS1/3 on input line 304. + +Package textcomp Info: Setting pxr sub-encoding to TS1/0 on input line 305. +Package textcomp Info: Setting pxss sub-encoding to TS1/0 on input line 306. +Package textcomp Info: Setting pxtt sub-encoding to TS1/0 on input line 307. +Package textcomp Info: Setting txr sub-encoding to TS1/0 on input line 308. +Package textcomp Info: Setting txss sub-encoding to TS1/0 on input line 309. +Package textcomp Info: Setting txtt sub-encoding to TS1/0 on input line 310. +Package textcomp Info: Setting futs sub-encoding to TS1/4 on input line 311. +Package textcomp Info: Setting futx sub-encoding to TS1/4 on input line 312. +Package textcomp Info: Setting futj sub-encoding to TS1/4 on input line 313. +Package textcomp Info: Setting hlh sub-encoding to TS1/3 on input line 314. +Package textcomp Info: Setting hls sub-encoding to TS1/3 on input line 315. +Package textcomp Info: Setting hlst sub-encoding to TS1/3 on input line 316. +Package textcomp Info: Setting hlct sub-encoding to TS1/5 on input line 317. +Package textcomp Info: Setting hlx sub-encoding to TS1/5 on input line 318. +Package textcomp Info: Setting hlce sub-encoding to TS1/5 on input line 319. +Package textcomp Info: Setting hlcn sub-encoding to TS1/5 on input line 320. +Package textcomp Info: Setting hlcw sub-encoding to TS1/5 on input line 321. +Package textcomp Info: Setting hlcf sub-encoding to TS1/5 on input line 322. +Package textcomp Info: Setting pplx sub-encoding to TS1/3 on input line 323. +Package textcomp Info: Setting pplj sub-encoding to TS1/3 on input line 324. +Package textcomp Info: Setting ptmx sub-encoding to TS1/4 on input line 325. +Package textcomp Info: Setting ptmj sub-encoding to TS1/4 on input line 326. +) (/usr/share/texmf-texlive/tex/latex/fancyhdr/fancyhdr.sty +\fancy@headwidth=\skip54 +\f@ncyO@elh=\skip55 +\f@ncyO@erh=\skip56 +\f@ncyO@olh=\skip57 +\f@ncyO@orh=\skip58 +\f@ncyO@elf=\skip59 +\f@ncyO@erf=\skip60 +\f@ncyO@olf=\skip61 +\f@ncyO@orf=\skip62 +) (/usr/share/texmf-texlive/tex/latex/fancybox/fancybox.sty +Package: fancybox 2000/09/19 1.3 +Style option: `fancybox' v1.3 <2000/09/19> (tvz) +\@fancybox=\box30 +\shadowsize=\dimen105 +\@Sbox=\box31 +\do@VerbBox=\toks17 +\the@fancyput=\toks18 +\this@fancyput=\toks19 +\EndVerbatimTokens=\toks20 +\Verbatim@Outfile=\write3 +\Verbatim@Infile=\read1 +) (/usr/share/texmf-texlive/tex/latex/titlesec/titlesec.sty +Package: titlesec 2007/08/12 v2.8 Sectioning titles +\ttl@box=\box32 +\beforetitleunit=\skip63 +\aftertitleunit=\skip64 +\ttl@plus=\dimen106 +\ttl@minus=\dimen107 +\ttl@toksa=\toks21 +\titlewidth=\dimen108 +\titlewidthlast=\dimen109 +\titlewidthfirst=\dimen110 +) (./tabulary.sty +Package: tabulary 2007/10/02 v0.9 tabulary package (DPC) +(/usr/share/texmf-texlive/tex/latex/tools/array.sty +Package: array 2008/09/09 v2.4c Tabular extension package (FMi) +\col@sep=\dimen111 +\extrarowheight=\dimen112 +\NC@list=\toks22 +\extratabsurround=\skip65 +\backup@length=\skip66 +) +\TY@count=\count96 +\TY@linewidth=\dimen113 +\tymin=\dimen114 +\tymax=\dimen115 +\TY@tablewidth=\dimen116 +) (/usr/share/texmf-texlive/tex/latex/amsmath/amsmath.sty +Package: amsmath 2000/07/18 v2.13 AMS math features +\@mathmargin=\skip67 +For additional information on amsmath, use the `?' option. +(/usr/share/texmf-texlive/tex/latex/amsmath/amstext.sty +Package: amstext 2000/06/29 v2.01 +(/usr/share/texmf-texlive/tex/latex/amsmath/amsgen.sty +File: amsgen.sty 1999/11/30 v2.0 +\@emptytoks=\toks23 +\ex@=\dimen117 +)) (/usr/share/texmf-texlive/tex/latex/amsmath/amsbsy.sty +Package: amsbsy 1999/11/29 v1.2d +\pmbraise@=\dimen118 +) (/usr/share/texmf-texlive/tex/latex/amsmath/amsopn.sty +Package: amsopn 1999/12/14 v2.01 operator names +) +\inf@bad=\count97 +LaTeX Info: Redefining \frac on input line 211. +\uproot@=\count98 +\leftroot@=\count99 +LaTeX Info: Redefining \overline on input line 307. +\classnum@=\count100 +\DOTSCASE@=\count101 +LaTeX Info: Redefining \ldots on input line 379. +LaTeX Info: Redefining \dots on input line 382. +LaTeX Info: Redefining \cdots on input line 467. +\Mathstrutbox@=\box33 +\strutbox@=\box34 +\big@size=\dimen119 +LaTeX Font Info: Redeclaring font encoding OML on input line 567. +LaTeX Font Info: Redeclaring font encoding OMS on input line 568. +\macc@depth=\count102 +\c@MaxMatrixCols=\count103 +\dotsspace@=\muskip10 +\c@parentequation=\count104 +\dspbrk@lvl=\count105 +\tag@help=\toks24 +\row@=\count106 +\column@=\count107 +\maxfields@=\count108 +\andhelp@=\toks25 +\eqnshift@=\dimen120 +\alignsep@=\dimen121 +\tagshift@=\dimen122 +\tagwidth@=\dimen123 +\totwidth@=\dimen124 +\lineht@=\dimen125 +\@envbody=\toks26 +\multlinegap=\skip68 +\multlinetaggap=\skip69 +\mathdisplay@stack=\toks27 +LaTeX Info: Redefining \[ on input line 2666. +LaTeX Info: Redefining \] on input line 2667. +) (/usr/share/texmf-texlive/tex/latex/base/makeidx.sty +Package: makeidx 2000/03/29 v1.0m Standard LaTeX package +) (/usr/share/texmf-texlive/tex/latex/ltxmisc/framed.sty +Package: framed 2007/10/04 v 0.95: framed or shaded text with page breaks +\fb@frw=\dimen126 +\fb@frh=\dimen127 +\FrameRule=\dimen128 +\FrameSep=\dimen129 +) (/usr/share/texmf-texlive/tex/latex/base/ifthen.sty +Package: ifthen 2001/05/26 v1.1c Standard LaTeX ifthen package (DPC) +) (/usr/share/texmf-texlive/tex/latex/graphics/color.sty +Package: color 2005/11/14 v1.0j Standard LaTeX Color (DPC) +(/etc/texmf/tex/latex/config/color.cfg +File: color.cfg 2007/01/18 v1.5 color configuration of teTeX/TeXLive +) +Package color Info: Driver file: pdftex.def on input line 130. +(/usr/share/texmf-texlive/tex/latex/pdftex-def/pdftex.def +File: pdftex.def 2010/03/12 v0.04p Graphics/color for pdfTeX +\Gread@gobject=\count109 +)) (/usr/share/texmf-texlive/tex/latex/fancyvrb/fancyvrb.sty +Package: fancyvrb 2008/02/07 + +Style option: `fancyvrb' v2.7a, with DG/SPQR fixes, and firstline=lastline fix +<2008/02/07> (tvz) (/usr/share/texmf-texlive/tex/latex/graphics/keyval.sty +Package: keyval 1999/03/16 v1.13 key=value parser (DPC) +\KV@toks@=\toks28 +) +\FV@CodeLineNo=\count110 +\FV@InFile=\read2 +\FV@TabBox=\box35 +\c@FancyVerbLine=\count111 +\FV@StepNumber=\count112 +\FV@OutFile=\write4 +) (/usr/share/texmf-texlive/tex/latex/ltxmisc/threeparttable.sty +Package: threeparttable 2003/06/13 v 3.0 +\@tempboxb=\box36 +) (/usr/share/texmf-texlive/tex/latex/mdwtools/footnote.sty +Package: footnote 1997/01/28 1.13 Save footnotes around boxes +\fn@notes=\box37 +\fn@width=\dimen130 +) (/usr/share/texmf-texlive/tex/latex/wrapfig/wrapfig.sty +\wrapoverhang=\dimen131 +\WF@size=\dimen132 +\c@WF@wrappedlines=\count113 +\WF@box=\box38 +\WF@everypar=\toks29 +Package: wrapfig 2003/01/31 v 3.6 +) (/usr/share/texmf-texlive/tex/latex/ltxmisc/parskip.sty +Package: parskip 2001/04/09 non-zero parskip adjustments +) (/usr/share/texmf-texlive/tex/latex/graphics/graphicx.sty +Package: graphicx 1999/02/16 v1.0f Enhanced LaTeX Graphics (DPC,SPQR) +(/usr/share/texmf-texlive/tex/latex/graphics/graphics.sty +Package: graphics 2009/02/05 v1.0o Standard LaTeX Graphics (DPC,SPQR) +(/usr/share/texmf-texlive/tex/latex/graphics/trig.sty +Package: trig 1999/03/16 v1.09 sin cos tan (DPC) +) (/etc/texmf/tex/latex/config/graphics.cfg +File: graphics.cfg 2009/08/28 v1.8 graphics configuration of TeX Live +) +Package graphics Info: Driver file: pdftex.def on input line 91. +) +\Gin@req@height=\dimen133 +\Gin@req@width=\dimen134 +) (/usr/share/texmf-texlive/tex/plain/misc/pdfcolor.tex) +\distancetoright=\skip70 +\py@argswidth=\skip71 +\py@noticelength=\skip72 +\lineblockindentation=\skip73 +\image@box=\box39 +\image@width=\dimen135 +(/usr/share/texmf-texlive/tex/latex/hyperref/hyperref.sty +Package: hyperref 2009/10/09 v6.79a Hypertext links for LaTeX +(/usr/share/texmf-texlive/tex/generic/oberdiek/ifpdf.sty +Package: ifpdf 2009/04/10 v2.0 Provides the ifpdf switch (HO) +Package ifpdf Info: pdfTeX in pdf mode detected. +) (/usr/share/texmf-texlive/tex/generic/oberdiek/ifvtex.sty +Package: ifvtex 2008/11/04 v1.4 Switches for detecting VTeX and its modes (HO) +Package ifvtex Info: VTeX not detected. +) (/usr/share/texmf-texlive/tex/generic/ifxetex/ifxetex.sty +Package: ifxetex 2009/01/23 v0.5 Provides ifxetex conditional +) (/usr/share/texmf-texlive/tex/latex/oberdiek/hycolor.sty +Package: hycolor 2009/10/02 v1.5 Code for color options of hyperref/bookmark (H +O) +(/usr/share/texmf-texlive/tex/latex/oberdiek/xcolor-patch.sty +Package: xcolor-patch 2009/10/02 xcolor patch +)) +\@linkdim=\dimen136 +\Hy@linkcounter=\count114 +\Hy@pagecounter=\count115 +(/usr/share/texmf-texlive/tex/latex/hyperref/pd1enc.def +File: pd1enc.def 2009/10/09 v6.79a Hyperref: PDFDocEncoding definition (HO) +Now handling font encoding PD1 ... +... no UTF-8 mapping file for font encoding PD1 +) (/usr/share/texmf-texlive/tex/generic/oberdiek/etexcmds.sty +Package: etexcmds 2007/12/12 v1.2 Prefix for e-TeX command names (HO) +(/usr/share/texmf-texlive/tex/generic/oberdiek/infwarerr.sty +Package: infwarerr 2007/09/09 v1.2 Providing info/warning/message (HO) +) +Package etexcmds Info: Could not find \expanded. +(etexcmds) That can mean that you are not using pdfTeX 1.50 or +(etexcmds) that some package has redefined \expanded. +(etexcmds) In the latter case, load this package earlier. +) (/usr/share/texmf-texlive/tex/latex/latexconfig/hyperref.cfg +File: hyperref.cfg 2002/06/06 v1.2 hyperref configuration of TeXLive +) (/usr/share/texmf-texlive/tex/latex/oberdiek/kvoptions.sty +Package: kvoptions 2009/08/13 v3.4 Keyval support for LaTeX options (HO) +(/usr/share/texmf-texlive/tex/generic/oberdiek/kvsetkeys.sty +Package: kvsetkeys 2009/07/30 v1.5 Key value parser with default handler suppor +t (HO) +)) +Package hyperref Info: Option `colorlinks' set `true' on input line 2864. +Package hyperref Info: Option `breaklinks' set `true' on input line 2864. +Package hyperref Info: Hyper figures OFF on input line 2975. +Package hyperref Info: Link nesting OFF on input line 2980. +Package hyperref Info: Hyper index ON on input line 2983. +Package hyperref Info: Plain pages OFF on input line 2990. +Package hyperref Info: Backreferencing OFF on input line 2995. +Implicit mode ON; LaTeX internals redefined +Package hyperref Info: Bookmarks ON on input line 3191. +(/usr/share/texmf-texlive/tex/latex/ltxmisc/url.sty +\Urlmuskip=\muskip11 +Package: url 2006/04/12 ver 3.3 Verb mode for urls, etc. +) +LaTeX Info: Redefining \url on input line 3428. +(/usr/share/texmf-texlive/tex/generic/oberdiek/bitset.sty +Package: bitset 2007/09/28 v1.0 Data type bit set (HO) +(/usr/share/texmf-texlive/tex/generic/oberdiek/intcalc.sty +Package: intcalc 2007/09/27 v1.1 Expandable integer calculations (HO) +) (/usr/share/texmf-texlive/tex/generic/oberdiek/bigintcalc.sty +Package: bigintcalc 2007/11/11 v1.1 Expandable big integer calculations (HO) +(/usr/share/texmf-texlive/tex/generic/oberdiek/pdftexcmds.sty +Package: pdftexcmds 2009/09/23 v0.6 LuaTeX support for pdfTeX utility functions + (HO) +(/usr/share/texmf-texlive/tex/generic/oberdiek/ifluatex.sty +Package: ifluatex 2009/04/17 v1.2 Provides the ifluatex switch (HO) +Package ifluatex Info: LuaTeX not detected. +) (/usr/share/texmf-texlive/tex/generic/oberdiek/ltxcmds.sty +Package: ltxcmds 2009/08/05 v1.0 Some LaTeX kernel commands for general use (HO +) +) +Package pdftexcmds Info: LuaTeX not detected. +Package pdftexcmds Info: \pdf@primitive is available. +Package pdftexcmds Info: \pdf@ifprimitive is available. +))) +\Fld@menulength=\count116 +\Field@Width=\dimen137 +\Fld@charsize=\dimen138 +\Field@toks=\toks30 +Package hyperref Info: Hyper figures OFF on input line 4377. +Package hyperref Info: Link nesting OFF on input line 4382. +Package hyperref Info: Hyper index ON on input line 4385. +Package hyperref Info: backreferencing OFF on input line 4392. +Package hyperref Info: Link coloring ON on input line 4395. +Package hyperref Info: Link coloring with OCG OFF on input line 4402. +Package hyperref Info: PDF/A mode OFF on input line 4407. +(/usr/share/texmf-texlive/tex/generic/oberdiek/atbegshi.sty +Package: atbegshi 2008/07/31 v1.9 At begin shipout hook (HO) +) +\Hy@abspage=\count117 +\c@Item=\count118 +\c@Hfootnote=\count119 +) +*hyperref using default driver hpdftex* +(/usr/share/texmf-texlive/tex/latex/hyperref/hpdftex.def +File: hpdftex.def 2009/10/09 v6.79a Hyperref driver for pdfTeX +\Fld@listcount=\count120 +) (/usr/share/texmf-texlive/tex/latex/oberdiek/hypcap.sty +Package: hypcap 2008/09/08 v1.10 Adjusting anchors of captions (HO) +) +\DUlineblockindent=\skip74 +) +\@indexfile=\write5 +\openout5 = `manual.idx'. + +Writing index file manual.idx +(./manual.aux) +\openout1 = `manual.aux'. + +LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line 109. +LaTeX Font Info: ... okay on input line 109. +LaTeX Font Info: Checking defaults for T1/cmr/m/n on input line 109. +LaTeX Font Info: ... okay on input line 109. +LaTeX Font Info: Checking defaults for OT1/cmr/m/n on input line 109. +LaTeX Font Info: ... okay on input line 109. +LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line 109. +LaTeX Font Info: ... okay on input line 109. +LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line 109. +LaTeX Font Info: ... okay on input line 109. +LaTeX Font Info: Checking defaults for U/cmr/m/n on input line 109. +LaTeX Font Info: ... okay on input line 109. +LaTeX Font Info: Checking defaults for TS1/cmr/m/n on input line 109. +LaTeX Font Info: Try loading font information for TS1+cmr on input line 109. + +(/usr/share/texmf-texlive/tex/latex/base/ts1cmr.fd +File: ts1cmr.fd 1999/05/25 v2.5h Standard LaTeX font definitions +) +LaTeX Font Info: ... okay on input line 109. +LaTeX Font Info: Checking defaults for PD1/pdf/m/n on input line 109. +LaTeX Font Info: ... okay on input line 109. +LaTeX Font Info: Try loading font information for T1+ptm on input line 109. +(/usr/share/texmf-texlive/tex/latex/psnfss/t1ptm.fd +File: t1ptm.fd 2001/06/04 font definitions for T1/ptm. +) (/usr/share/texmf-texlive/tex/context/base/supp-pdf.mkii +[Loading MPS to PDF converter (version 2006.09.02).] +\scratchcounter=\count121 +\scratchdimen=\dimen139 +\scratchbox=\box40 +\nofMPsegments=\count122 +\nofMParguments=\count123 +\everyMPshowfont=\toks31 +\MPscratchCnt=\count124 +\MPscratchDim=\dimen140 +\MPnumerator=\count125 +\everyMPtoPDFconversion=\toks32 +) +Package hyperref Info: Link coloring ON on input line 109. +(/usr/share/texmf-texlive/tex/latex/hyperref/nameref.sty +Package: nameref 2007/05/29 v2.31 Cross-referencing by name of section +(/usr/share/texmf-texlive/tex/latex/oberdiek/refcount.sty +Package: refcount 2008/08/11 v3.1 Data extraction from references (HO) +) +\c@section@level=\count126 +) +LaTeX Info: Redefining \ref on input line 109. +LaTeX Info: Redefining \pageref on input line 109. +(./manual.out) (./manual.out) +\@outlinefile=\write6 +\openout6 = `manual.out'. + +\AtBeginShipoutBox=\box41 + +Underfull \hbox (badness 10000) in paragraph at lines 112--112 + + [] + +LaTeX Font Info: Try loading font information for T1+phv on input line 112. +(/usr/share/texmf-texlive/tex/latex/psnfss/t1phv.fd +File: t1phv.fd 2001/06/04 scalable font definitions for T1/phv. +) +LaTeX Font Info: Font shape `T1/phv/bx/n' in size <24.88> not available +(Font) Font shape `T1/phv/b/n' tried instead on input line 112. +LaTeX Font Info: Font shape `T1/phv/m/it' in size <17.28> not available +(Font) Font shape `T1/phv/m/sl' tried instead on input line 112. +LaTeX Font Info: Font shape `T1/phv/bx/it' in size <17.28> not available +(Font) Font shape `T1/phv/b/it' tried instead on input line 112. +LaTeX Font Info: Font shape `T1/phv/b/it' in size <17.28> not available +(Font) Font shape `T1/phv/b/sl' tried instead on input line 112. +LaTeX Font Info: Font shape `T1/phv/bx/n' in size <17.28> not available +(Font) Font shape `T1/phv/b/n' tried instead on input line 112. +[1 + +{/home/nikratio/.texmf-var/fonts/map/pdftex/updmap/pdftex.map + +pdfTeX warning: pdflatex (file /home/nikratio/.texmf-var/fonts/map/pdftex/updma +p/pdftex.map): fontmap entry for `ugqb8r' already exists, duplicates ignored + + +pdfTeX warning: pdflatex (file /home/nikratio/.texmf-var/fonts/map/pdftex/updma +p/pdftex.map): fontmap entry for `ugqbo8r' already exists, duplicates ignored +}] [2 + +] (./manual.toc +LaTeX Font Info: Font shape `T1/ptm/bx/n' in size <10> not available +(Font) Font shape `T1/ptm/b/n' tried instead on input line 2. +LaTeX Font Info: Try loading font information for T1+pcr on input line 10. +(/usr/share/texmf-texlive/tex/latex/psnfss/t1pcr.fd +File: t1pcr.fd 2001/06/04 font definitions for T1/pcr. +) +LaTeX Font Info: Font shape `T1/phv/bx/n' in size <10> not available +(Font) Font shape `T1/phv/b/n' tried instead on input line 38. +pdfTeX warning (ext4): destination with the same identifier (name{page.i}) has +been already used, duplicate ignored +<to be read again> + \relax +l.38 ...ine {9}Checking for Errors}{23}{chapter.9} + [1 + +]) +\tf@toc=\write7 +\openout7 = `manual.toc'. + +pdfTeX warning (ext4): destination with the same identifier (name{page.ii}) has + been already used, duplicate ignored +<to be read again> + \relax +l.112 \tableofcontents + [2] +Chapter 1. +LaTeX Font Info: Font shape `T1/phv/bx/n' in size <14.4> not available +(Font) Font shape `T1/phv/b/n' tried instead on input line 117. +LaTeX Font Info: Try loading font information for TS1+ptm on input line 140. + +(/usr/share/texmf-texlive/tex/latex/psnfss/ts1ptm.fd +File: ts1ptm.fd 2001/06/04 font definitions for TS1/ptm. +) [1 + + +] [2] +Chapter 2. +[3 + +] [4] +Chapter 3. + +Underfull \hbox (badness 10000) in paragraph at lines 346--347 + + [] + +[5 + +] +LaTeX Font Info: Font shape `T1/pcr/bx/n' in size <14.4> not available +(Font) Font shape `T1/pcr/b/n' tried instead on input line 402. +LaTeX Font Info: Font shape `T1/phv/bx/n' in size <12> not available +(Font) Font shape `T1/phv/b/n' tried instead on input line 462. +[6] [7] +LaTeX Font Info: Font shape `T1/pcr/m/it' in size <9> not available +(Font) Font shape `T1/pcr/m/sl' tried instead on input line 607. +[8] +Chapter 4. +[9 + +] [10 + +] +Chapter 5. +[11] +Underfull \hbox (badness 10000) in paragraph at lines 777--778 + + [] + +[12] +Chapter 6. +[13 + +] [14] [15] [16] +Chapter 7. +[17 + +] [18] [19] [20 + +] +Chapter 8. +[21] [22 + +] +Chapter 9. +[23] [24 + +] +Chapter 10. +[25] +Underfull \hbox (badness 10000) in paragraph at lines 1439--1444 +[]\T1/ptm/b/n/10 expire_backups \T1/ptm/m/n/10 us-age is sim-ple. It re-quires +back-ups to have names of the forms + [] + +[26] [27] [28 + +] +Chapter 11. +[29] [30] +Chapter 12. +[31 + +] [32] +Chapter 13. +[33 + +] [34] [35] [36] [37] [38] [39] [40] [41] [42] [43] [44] [45] +Underfull \hbox (badness 10000) in paragraph at lines 2672--2677 +[]\T1/ptm/b/n/10 expire_backups \T1/ptm/m/n/10 us-age is sim-ple. It re-quires +back-ups to have names of the forms + [] + +[46] [47] [48 + +] +Chapter 14. +No file manual.ind. +[49] (./manual.aux) ) +Here is how much of TeX's memory you used: + 8345 strings out of 495021 + 113597 string characters out of 1181035 + 200143 words of memory out of 3000000 + 11122 multiletter control sequences out of 15000+50000 + 59136 words of font info for 67 fonts, out of 3000000 for 9000 + 29 hyphenation exceptions out of 8191 + 45i,12n,48p,275b,492s stack positions out of 5000i,500n,10000p,200000b,50000s +{/usr/share/texmf-texlive/fonts/enc/dvips/base/8r.enc}</us +r/share/texmf-texlive/fonts/type1/urw/courier/ucrb8a.pfb></usr/share/texmf-texl +ive/fonts/type1/urw/courier/ucrr8a.pfb></usr/share/texmf-texlive/fonts/type1/ur +w/courier/ucrro8a.pfb></usr/share/texmf-texlive/fonts/type1/urw/helvetic/uhvb8a +.pfb></usr/share/texmf-texlive/fonts/type1/urw/helvetic/uhvbo8a.pfb></usr/share +/texmf-texlive/fonts/type1/urw/times/utmb8a.pfb></usr/share/texmf-texlive/fonts +/type1/urw/times/utmr8a.pfb></usr/share/texmf-texlive/fonts/type1/urw/times/utm +ri8a.pfb> +Output written on manual.pdf (53 pages, 289155 bytes). +PDF statistics: + 781 PDF objects out of 1000 (max. 8388607) + 224 named destinations out of 1000 (max. 500000) + 465 words of extra memory for PDF output out of 10000 (max. 10000000) + diff --git a/doc/latex/manual.out b/doc/latex/manual.out new file mode 100644 index 0000000..16ea0d1 --- /dev/null +++ b/doc/latex/manual.out @@ -0,0 +1,58 @@ +\BOOKMARK [0][-]{chapter.1}{About S3QL}{} +\BOOKMARK [1][-]{section.1.1}{Features}{chapter.1} +\BOOKMARK [1][-]{section.1.2}{Development Status}{chapter.1} +\BOOKMARK [0][-]{chapter.2}{Installation}{} +\BOOKMARK [1][-]{section.2.1}{Dependencies}{chapter.2} +\BOOKMARK [1][-]{section.2.2}{Installing S3QL}{chapter.2} +\BOOKMARK [0][-]{chapter.3}{Storage Backends}{} +\BOOKMARK [1][-]{section.3.1}{On Backend Reliability}{chapter.3} +\BOOKMARK [1][-]{section.3.2}{The authinfo file}{chapter.3} +\BOOKMARK [1][-]{section.3.3}{Consistency Guarantees}{chapter.3} +\BOOKMARK [1][-]{section.3.4}{The Amazon S3 Backend}{chapter.3} +\BOOKMARK [1][-]{section.3.5}{The Local Backend}{chapter.3} +\BOOKMARK [1][-]{section.3.6}{The SFTP Backend}{chapter.3} +\BOOKMARK [0][-]{chapter.4}{File System Creation}{} +\BOOKMARK [0][-]{chapter.5}{Managing Buckets}{} +\BOOKMARK [1][-]{section.5.1}{Changing the Passphrase}{chapter.5} +\BOOKMARK [1][-]{section.5.2}{Upgrading the file system}{chapter.5} +\BOOKMARK [1][-]{section.5.3}{Deleting a file system}{chapter.5} +\BOOKMARK [1][-]{section.5.4}{Restoring Metadata Backups}{chapter.5} +\BOOKMARK [0][-]{chapter.6}{Mounting}{} +\BOOKMARK [1][-]{section.6.1}{Storing Encryption Passwords}{chapter.6} +\BOOKMARK [1][-]{section.6.2}{Compression Algorithms}{chapter.6} +\BOOKMARK [1][-]{section.6.3}{Parallel Compression}{chapter.6} +\BOOKMARK [1][-]{section.6.4}{Notes about Caching}{chapter.6} +\BOOKMARK [1][-]{section.6.5}{Automatic Mounting}{chapter.6} +\BOOKMARK [0][-]{chapter.7}{Advanced S3QL Features}{} +\BOOKMARK [1][-]{section.7.1}{Snapshotting and Copy-on-Write}{chapter.7} +\BOOKMARK [1][-]{section.7.2}{Getting Statistics}{chapter.7} +\BOOKMARK [1][-]{section.7.3}{Immutable Trees}{chapter.7} +\BOOKMARK [1][-]{section.7.4}{Fast Recursive Removal}{chapter.7} +\BOOKMARK [1][-]{section.7.5}{Runtime Configuration}{chapter.7} +\BOOKMARK [0][-]{chapter.8}{Unmounting}{} +\BOOKMARK [0][-]{chapter.9}{Checking for Errors}{} +\BOOKMARK [0][-]{chapter.10}{Contributed Programs}{} +\BOOKMARK [1][-]{section.10.1}{benchmark.py}{chapter.10} +\BOOKMARK [1][-]{section.10.2}{s3\137copy.py}{chapter.10} +\BOOKMARK [1][-]{section.10.3}{pcp.py}{chapter.10} +\BOOKMARK [1][-]{section.10.4}{s3\137backup.sh}{chapter.10} +\BOOKMARK [1][-]{section.10.5}{expire\137backups.py}{chapter.10} +\BOOKMARK [1][-]{section.10.6}{s3ql.conf}{chapter.10} +\BOOKMARK [0][-]{chapter.11}{Tips \046 Tricks}{} +\BOOKMARK [1][-]{section.11.1}{Permanently mounted backup file system}{chapter.11} +\BOOKMARK [1][-]{section.11.2}{Improving copy performance}{chapter.11} +\BOOKMARK [0][-]{chapter.12}{Known Issues}{} +\BOOKMARK [0][-]{chapter.13}{Manpages}{} +\BOOKMARK [1][-]{section.13.1}{The mkfs.s3ql command}{chapter.13} +\BOOKMARK [1][-]{section.13.2}{The s3qladm command}{chapter.13} +\BOOKMARK [1][-]{section.13.3}{The mount.s3ql command}{chapter.13} +\BOOKMARK [1][-]{section.13.4}{The s3qlstat command}{chapter.13} +\BOOKMARK [1][-]{section.13.5}{The s3qlctrl command}{chapter.13} +\BOOKMARK [1][-]{section.13.6}{The s3qlcp command}{chapter.13} +\BOOKMARK [1][-]{section.13.7}{The s3qlrm command}{chapter.13} +\BOOKMARK [1][-]{section.13.8}{The s3qllock command}{chapter.13} +\BOOKMARK [1][-]{section.13.9}{The umount.s3ql command}{chapter.13} +\BOOKMARK [1][-]{section.13.10}{The fsck.s3ql command}{chapter.13} +\BOOKMARK [1][-]{section.13.11}{The pcp command}{chapter.13} +\BOOKMARK [1][-]{section.13.12}{The expire\137backups command}{chapter.13} +\BOOKMARK [0][-]{chapter.14}{Further Resources / Getting Help}{} diff --git a/doc/latex/manual.tex b/doc/latex/manual.tex new file mode 100644 index 0000000..fe2532b --- /dev/null +++ b/doc/latex/manual.tex @@ -0,0 +1,2761 @@ +% Generated by Sphinx. +\def\sphinxdocclass{report} +\documentclass[letterpaper,10pt,english]{sphinxmanual} +\usepackage[utf8]{inputenc} +\DeclareUnicodeCharacter{00A0}{\nobreakspace} +\usepackage[T1]{fontenc} +\usepackage{babel} +\usepackage{times} +\usepackage[Bjarne]{fncychap} +\usepackage{longtable} +\usepackage{sphinx} + + +\title{S3QL Documentation} +\date{May 20, 2011} +\release{1.0.1} +\author{Nikolaus Rath} +\newcommand{\sphinxlogo}{} +\renewcommand{\releasename}{Release} +\makeindex + +\makeatletter +\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax% + \let\PYG@ul=\relax \let\PYG@tc=\relax% + \let\PYG@bc=\relax \let\PYG@ff=\relax} +\def\PYG@tok#1{\csname PYG@tok@#1\endcsname} +\def\PYG@toks#1+{\ifx\relax#1\empty\else% + \PYG@tok{#1}\expandafter\PYG@toks\fi} +\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{% + \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}} +\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}} + +\def\PYG@tok@gd{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}} +\def\PYG@tok@gu{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}} +\def\PYG@tok@gt{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.25,0.82}{##1}}} +\def\PYG@tok@gs{\let\PYG@bf=\textbf} +\def\PYG@tok@gr{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}} +\def\PYG@tok@cm{\def\PYG@tc##1{\textcolor[rgb]{0.50,0.50,0.50}{##1}}} +\def\PYG@tok@vg{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.82,0.44,0.00}{##1}}} +\def\PYG@tok@m{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.38,0.00,0.88}{##1}}} +\def\PYG@tok@mh{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.31,0.50}{##1}}} +\def\PYG@tok@cs{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.80,0.00,0.00}{##1}}} +\def\PYG@tok@ge{\let\PYG@it=\textit} +\def\PYG@tok@vc{\def\PYG@tc##1{\textcolor[rgb]{0.19,0.38,0.56}{##1}}} +\def\PYG@tok@il{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.82}{##1}}} +\def\PYG@tok@go{\def\PYG@tc##1{\textcolor[rgb]{0.50,0.50,0.50}{##1}}} +\def\PYG@tok@cp{\def\PYG@tc##1{\textcolor[rgb]{0.31,0.44,0.56}{##1}}} +\def\PYG@tok@gi{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}} +\def\PYG@tok@gh{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}} +\def\PYG@tok@ni{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.00}{##1}}} +\def\PYG@tok@nl{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.56,0.44,0.00}{##1}}} +\def\PYG@tok@nn{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}} +\def\PYG@tok@no{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.19,0.38}{##1}}} +\def\PYG@tok@na{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.75}{##1}}} +\def\PYG@tok@nb{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} +\def\PYG@tok@nc{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.69,0.00,0.38}{##1}}} +\def\PYG@tok@nd{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.31,0.31,0.31}{##1}}} +\def\PYG@tok@ne{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.94,0.00,0.00}{##1}}} +\def\PYG@tok@nf{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.38,0.69}{##1}}} +\def\PYG@tok@si{\def\PYG@bc##1{\colorbox[rgb]{0.88,0.88,0.88}{##1}}} +\def\PYG@tok@s2{\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}} +\def\PYG@tok@vi{\def\PYG@tc##1{\textcolor[rgb]{0.19,0.19,0.69}{##1}}} +\def\PYG@tok@nt{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.00}{##1}}} +\def\PYG@tok@nv{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.38,0.19}{##1}}} +\def\PYG@tok@s1{\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}} +\def\PYG@tok@gp{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}} +\def\PYG@tok@sh{\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}} +\def\PYG@tok@ow{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.00}{##1}}} +\def\PYG@tok@sx{\def\PYG@tc##1{\textcolor[rgb]{0.82,0.13,0.00}{##1}}\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}} +\def\PYG@tok@bp{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}} +\def\PYG@tok@c1{\def\PYG@tc##1{\textcolor[rgb]{0.50,0.50,0.50}{##1}}} +\def\PYG@tok@kc{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.50,0.00}{##1}}} +\def\PYG@tok@c{\def\PYG@tc##1{\textcolor[rgb]{0.50,0.50,0.50}{##1}}} +\def\PYG@tok@mf{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.38,0.00,0.88}{##1}}} +\def\PYG@tok@err{\def\PYG@tc##1{\textcolor[rgb]{0.94,0.00,0.00}{##1}}\def\PYG@bc##1{\colorbox[rgb]{0.94,0.63,0.63}{##1}}} +\def\PYG@tok@kd{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.50,0.00}{##1}}} +\def\PYG@tok@ss{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.38,0.00}{##1}}} +\def\PYG@tok@sr{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.00}{##1}}\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,1.00}{##1}}} +\def\PYG@tok@mo{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.00,0.88}{##1}}} +\def\PYG@tok@mi{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.82}{##1}}} +\def\PYG@tok@kn{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.50,0.00}{##1}}} +\def\PYG@tok@o{\def\PYG@tc##1{\textcolor[rgb]{0.19,0.19,0.19}{##1}}} +\def\PYG@tok@kr{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.50,0.00}{##1}}} +\def\PYG@tok@s{\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}} +\def\PYG@tok@kp{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.19,0.50}{##1}}} +\def\PYG@tok@w{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}} +\def\PYG@tok@kt{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.19,0.19,0.56}{##1}}} +\def\PYG@tok@sc{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.25,0.82}{##1}}} +\def\PYG@tok@sb{\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}} +\def\PYG@tok@k{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.50,0.00}{##1}}} +\def\PYG@tok@se{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.38,0.38,0.38}{##1}}\def\PYG@bc##1{\colorbox[rgb]{1.00,0.94,0.94}{##1}}} +\def\PYG@tok@sd{\def\PYG@tc##1{\textcolor[rgb]{0.82,0.25,0.13}{##1}}} + +\def\PYGZbs{\char`\\} +\def\PYGZus{\char`\_} +\def\PYGZob{\char`\{} +\def\PYGZcb{\char`\}} +\def\PYGZca{\char`\^} +\def\PYGZsh{\char`\#} +\def\PYGZpc{\char`\%} +\def\PYGZdl{\char`\$} +\def\PYGZti{\char`\~} +% for compatibility with earlier versions +\def\PYGZat{@} +\def\PYGZlb{[} +\def\PYGZrb{]} +\makeatother + +\begin{document} + +\maketitle +\tableofcontents +\phantomsection\label{index::doc} + + + +\chapter{About S3QL} +\label{about:about-s3ql}\label{about::doc}\label{about:s3ql-user-s-guide} +S3QL is a file system that stores all its data online. It supports +\href{http://aws.amazon.com/s3AmazonS3}{Amazon S3} as well as arbitrary +SFTP servers and effectively provides you with a hard disk of dynamic, +infinite capacity that can be accessed from any computer with internet +access. + +S3QL is providing a standard, full featured UNIX file system that is +conceptually indistinguishable from any local file system. +Furthermore, S3QL has additional features like compression, +encryption, data de-duplication, immutable trees and snapshotting +which make it especially suitable for online backup and archival. + +S3QL is designed to favor simplicity and elegance over performance and +feature-creep. Care has been taken to make the source code as +readable and serviceable as possible. Solid error detection and error +handling have been included from the very first line, and S3QL comes +with extensive automated test cases for all its components. + + +\section{Features} +\label{about:features}\begin{itemize} +\item {} +\textbf{Transparency.} Conceptually, S3QL is indistinguishable from a +local file system. For example, it supports hardlinks, symlinks, +ACLs and standard unix permissions, extended attributes and file +sizes up to 2 TB. + +\item {} +\textbf{Dynamic Size.} The size of an S3QL file system grows and shrinks +dynamically as required. + +\item {} +\textbf{Compression.} Before storage, all data may compressed with the +LZMA, bzip2 or deflate (gzip) algorithm. + +\item {} +\textbf{Encryption.} After compression (but before upload), all data can +AES encrypted with a 256 bit key. An additional SHA256 HMAC checksum +is used to protect the data against manipulation. + +\item {} +\textbf{Data De-duplication.} If several files have identical contents, +the redundant data will be stored only once. This works across all +files stored in the file system, and also if only some parts of the +files are identical while other parts differ. + +\item {} +\textbf{Immutable Trees.} Directory trees can be made immutable, so that +their contents can no longer be changed in any way whatsoever. This +can be used to ensure that backups can not be modified after they +have been made. + +\item {} +\textbf{Copy-on-Write/Snapshotting.} S3QL can replicate entire directory +trees without using any additional storage space. Only if one of the +copies is modified, the part of the data that has been modified will +take up additional storage space. This can be used to create +intelligent snapshots that preserve the state of a directory at +different points in time using a minimum amount of space. + +\item {} +\textbf{High Performance independent of network latency.} All operations +that do not write or read file contents (like creating directories +or moving, renaming, and changing permissions of files and +directories) are very fast because they are carried out without any +network transactions. + +S3QL achieves this by saving the entire file and directory structure +in a database. This database is locally cached and the remote +copy updated asynchronously. + +\item {} +\textbf{Support for low bandwidth connections.} S3QL splits file contents +into smaller blocks and caches blocks locally. This minimizes both +the number of network transactions required for reading and writing +data, and the amount of data that has to be transferred when only +parts of a file are read or written. + +\end{itemize} + + +\section{Development Status} +\label{about:development-status} +After two years of beta-testing by about 93 users did not reveal any +data-critical bugs, S3QL was declared \textbf{stable} with the release of +version 1.0 on May 13th, 2011. Note that this does not mean that S3QL +is bug-free. S3QL still has several known, and probably many more +unknown bugs. However, there is a high probability that these bugs +will, although being inconvenient, not endanger any stored data. + +Please report any problems on the \href{http://groups.google.com/group/s3ql}{mailing list} or the \href{http://code.google.com/p/s3ql/issues/list}{issue tracker}. + + +\chapter{Installation} +\label{installation:installation}\label{installation::doc} +S3QL depends on several other programs and libraries that have to be +installed first. The best method to satisfy these dependencies depends +on your distribution. In some cases S3QL and all its dependencies can +be installed with as little as three commands, while in other cases more work +may be required. + +The \href{http://code.google.com/p/s3ql/w/list}{S3QL Wiki} contains +installation instructions for quite a few different Linux +distributions. You should only use the generic instructions in this +manual if your distribution is not included in the \href{http://code.google.com/p/s3ql/w/list?q=label:Installation}{distribution-specific +installation instructions} on the wiki. + + +\section{Dependencies} +\label{installation:dependencies} +The following is a list of the programs and libraries required for +running S3QL. Generally, you should first check if your distribution +already provides a suitable packages and only install from source if +that is not the case. +\begin{itemize} +\item {} +Kernel version 2.6.9 or newer. Starting with kernel 2.6.26 +you will get significantly better write performance, so you should +actually use \emph{2.6.26 or newer whenever possible}. + +\item {} +The \href{http://fuse.sourceforge.net/}{FUSE Library} should already be +installed on your system. However, you have to make sure that you +have at least version 2.8.0. + +\item {} +The \href{http://pypi.python.org/pypi/pycryptopp}{PyCrypto++ Python Module}. To check if this module +is installed, try to execute \code{python -c 'import pycryptopp'}. + +\item {} +The \href{http://pypi.python.org/pypi/argparse}{argparse Python Module}. To check if this module is +installed, try to execute \code{python -c 'import argparse; print +argparse.\_\_version\_\_'}. If argparse is installed, this will print +the version number. You need version 1.1 or later. + +\item {} +The \href{http://code.google.com/p/apsw/}{APSW Python Module}. To check +which (if any) version of APWS is installed, run the command + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{python -c 'import apsw; print apsw.apswversion(), apsw.sqlitelibversion()'} +\end{Verbatim} + +If APSW is installed, this should print two version numbers which +both have to be at least 3.7.0. + +\item {} +The \href{http://pypi.python.org/pypi/pyliblzma}{PyLibLZMA Python module}. To check if this module +is installed, execute \code{python -c 'import lzma; print +lzma.\_\_version\_\_'}. This should print a version number. You need at +least version 0.5.3. + +\item {} +The \href{http://code.google.com/p/python-llfuse/}{Python LLFUSE module}. To check if this module +is installed, execute \code{python -c 'import llfuse; print +llfuse.\_\_version\_\_'}. This should print a version number. You need at +least version 0.29. + +Note that earlier S3QL versions shipped with a builtin version of +this module. If you are upgrading from such a version, make sure to +completely remove the old S3QL version first. + +\item {} +If you want to use the SFTP backend, then you also need the +\href{http://www.lag.net/paramiko/}{Paramiko Python Module}. To check +if this module is installed, try to execute \code{python -c 'import +paramiko'}. + +\end{itemize} + + +\section{Installing S3QL} +\label{installation:inst-s3ql}\label{installation:installing-s3ql} +To install S3QL itself, proceed as follows: +\begin{enumerate} +\item {} +Download S3QL from \href{http://code.google.com/p/s3ql/downloads/list}{http://code.google.com/p/s3ql/downloads/list} + +\item {} +Unpack it into a folder of your choice + +\item {} +Run \code{python setup.py test} to run a self-test. If this fails, ask +for help on the \href{http://groups.google.com/group/s3ql}{mailing list} or report a bug in the +\href{http://code.google.com/p/s3ql/issues/list}{issue tracker}. + +\end{enumerate} + +Now you have three options: +\begin{itemize} +\item {} +You can run the S3QL commands from the \code{bin/} directory. + +\item {} +You can install S3QL system-wide for all users. To do that, you +have to run \code{sudo python setup.py install}. + +\item {} +You can install S3QL into \code{\textasciitilde{}/.local} by executing \code{python +setup.py install -{-}user}. In this case you should make sure that +\code{\textasciitilde{}/.local/bin} is in your \code{\$PATH} environment variable. + +\end{itemize} + + +\chapter{Storage Backends} +\label{backends::doc}\label{backends:storage-backends} +S3QL can use different protocols to store the file system data. +Independent of the backend that you use, the place where your file +system data is being stored is called a \emph{bucket}. (This is mostly for +historical reasons, since initially S3QL supported only the Amazon S3 +backend). + + +\section{On Backend Reliability} +\label{backends:on-backend-reliability} +S3QL has been designed for use with a storage backend where data loss +is so infrequent that it can be completely neglected (e.g. the Amazon +S3 backend). If you decide to use a less reliable backend, you should +keep the following warning in mind and read this section carefully. + +\begin{notice}{warning}{Warning:} +S3QL is not able to compensate for any failures of the backend. In +particular, it is not able reconstruct any data that has been lost +or corrupted by the backend. The persistence and durability of data +stored in an S3QL file system is limited and determined by the +backend alone. +\end{notice} + +On the plus side, if a backend looses or corrupts some of the stored +data, S3QL \emph{will} detect the problem. Missing data will be detected +when running \code{fsck.s3ql} or when attempting to access the data in the +mounted file system. In the later case you will get an IO Error, and +on unmounting S3QL will warn you that the file system is damaged and +you need to run \code{fsck.s3ql}. + +\code{fsck.s3ql} will report all the affected files and move them into the +\code{/lost+found} directory of the file system. + +You should be aware that, because of S3QL's data de-duplication +feature, the consequences of a data loss in the backend can be +significantly more severe than you may expect. More concretely, a data +loss in the backend at time \emph{x} may cause data that is written \emph{after} +time \emph{x} to be lost as well. What may happen is this: +\begin{enumerate} +\item {} +You store an important file in the S3QL file system. + +\item {} +The backend looses the data blocks of this file. As long as you +do not access the file or run \code{fsck.s3ql}, S3QL +is not aware that the data has been lost by the backend. + +\item {} +You save an additional copy of the important file in a different +location on the same S3QL file system. + +\item {} +S3QL detects that the contents of the new file are identical to the +data blocks that have been stored earlier. Since at this point S3QL +is not aware that these blocks have been lost by the backend, it +does not save another copy of the file contents in the backend but +relies on the (presumably) existing blocks instead. + +\item {} +Therefore, even though you saved another copy, you still do not +have a backup of the important file (since both copies refer to the +same data blocks that have been lost by the backend). + +\end{enumerate} + +As one can see, this effect becomes the less important the more often +one runs \code{fsck.s3ql}, since \code{fsck.s3ql} will make S3QL aware of any +blocks that the backend may have lost. Figuratively, this establishes +a ``checkpoint'': data loss in the backend that occurred before running +\code{fsck.s3ql} can not affect any file system operations performed after +running \code{fsck.s3ql}. + +Nevertheless, (as said at the beginning) the recommended way to use +S3QL is in combination with a sufficiently reliable storage backend. +In that case none of the above will ever be a concern. + + +\section{The \texttt{authinfo} file} +\label{backends:the-authinfo-file} +Most backends first try to read the file \code{\textasciitilde{}/.s3ql/authinfo} to determine +the username and password for connecting to the remote host. If this +fails, both username and password are read from the terminal. + +The \code{authinfo} file has to contain entries of the form + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{backend }\PYG{n+nv}{\textless{}backend\textgreater{}}\PYG{l}{ machine }\PYG{n+nv}{\textless{}host\textgreater{}}\PYG{l}{ login }\PYG{n+nv}{\textless{}user\textgreater{}}\PYG{l}{ password }\PYG{n+nv}{\textless{}password\textgreater{}} +\end{Verbatim} + +So to use the login \code{joe} with password \code{jibbadup} when using the FTP +backend to connect to the host \code{backups.joesdomain.com}, you would +specify + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{backend ftp machine backups.joesdomain.com login joe password jibbadup} +\end{Verbatim} + + +\section{Consistency Guarantees} +\label{backends:consistency-guarantees} +The different backends provide different types of \emph{consistency +guarantees}. Informally, a consistency guarantee tells you how fast +the backend will apply changes to the stored data. + +S3QL defines the following three levels: +\begin{itemize} +\item {} +\textbf{Read-after-Write Consistency.} This is the strongest consistency +guarantee. If a backend offers read-after-write consistency, it +guarantees that as soon as you have committed any changes to the +backend, subsequent requests will take into account these changes. + +\item {} +\textbf{Read-after-Create Consistency.} If a backend provides only +read-after-create consistency, only the creation of a new object is +guaranteed to be taken into account for subsequent requests. This +means that, for example, if you overwrite data in an existing +object, subsequent requests may still return the old data for a +certain period of time. + +\item {} +\textbf{Eventual consistency.} This is the lowest consistency level. +Basically, any changes that you make to the backend may not be +visible for a certain amount of time after the change has been made. +However, you are guaranteed that no change will be lost. All changes +will \emph{eventually} become visible. + +. + +\end{itemize} + +As long as your backend provides read-after-write or read-after-create +consistency, you do not have to worry about consistency guarantees at +all. However, if you plan to use a backend with only eventual +consistency, you have to be a bit careful in some situations. + + +\subsection{Dealing with Eventual Consistency} +\label{backends:dealing-with-eventual-consistency}\label{backends:eventual-consistency} +\begin{notice}{note}{Note:} +The following applies only to storage backends that do not provide +read-after-create or read-after-write consistency. Currently, +this is only the Amazon S3 backend \emph{if used with the US-Standard +storage region}. If you use a different storage backend, or the S3 +backend with a different storage region, this section does not apply +to you. +\end{notice} + +While the file system is mounted, S3QL is able to automatically handle +all issues related to the weak eventual consistency guarantee. +However, some issues may arise during the mount process and when the +file system is checked. + +Suppose that you mount the file system, store some new data, delete +some old data and unmount it again. Now remember that eventual +consistency means that there is no guarantee that these changes will +be visible immediately. At least in theory it is therefore possible +that if you mount the file system again, S3QL does not see any of the +changes that you have done and presents you an ``old version'' of the +file system without them. Even worse, if you notice the problem and +unmount the file system, S3QL will upload the old status (which S3QL +necessarily has to consider as current) and thereby permanently +override the newer version (even though this change may not become +immediately visible either). + +The same problem applies when checking the file system. If the backend +provides S3QL with only partially updated data, S3QL has no way to +find out if this a real consistency problem that needs to be fixed or +if it is only a temporary problem that will resolve itself +automatically (because there are still changes that have not become +visible yet). + +While this may seem to be a rather big problem, the likelihood of it +to occur is rather low. In practice, most storage providers rarely +need more than a few seconds to apply incoming changes, so to trigger +this problem one would have to unmount and remount the file system in +a very short time window. Many people therefore make sure that they +wait a few minutes between successive mounts (or file system checks) +and decide that the remaining risk is negligible. + +Nevertheless, the eventual consistency guarantee does not impose an +upper limit on the time that it may take for change to become visible. +Therefore there is no ``totally safe'' waiting time that would totally +eliminate this problem; a theoretical possibility always remains. + + +\section{The Amazon S3 Backend} +\label{backends:the-amazon-s3-backend} +To store your file system in an Amazon S3 bucket, use a storage URL of +the form \code{s3://\textless{}bucketname\textgreater{}}. Bucket names must conform to the \href{http://docs.amazonwebservices.com/AmazonS3/2006-03-01/dev/BucketRestrictions.html}{S3 +Bucket Name Restrictions}. + +The S3 backend offers exceptionally strong reliability guarantees. As +of August 2010, Amazon guarantees a durability of 99.999999999\% per +year. In other words, if you store a thousand million objects then on +average you would loose less than one object in a hundred years. + +The Amazon S3 backend provides read-after-create consistency for the +EU, Asia-Pacific and US-West storage regions. \emph{For the US-Standard +storage region, Amazon S3 provides only eventual consistency} (please +refer to {\hyperref[backends:eventual-consistency]{\emph{Dealing with Eventual Consistency}}} for information about +what this entails). + +When connecting to Amazon S3, S3QL uses an unencrypted HTTP +connection, so if you want your data to stay confidential, you have +to create the S3QL file system with encryption (this is also the default). + +When reading the authentication information for the S3 backend from +the \code{authinfo} file, the \code{host} field is ignored, i.e. the first entry +with \code{s3} as a backend will be used. For example + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{backend s3 machine any login myAWSaccessKeyId password myAwsSecretAccessKey} +\end{Verbatim} + +Note that the bucket names come from a global pool, so chances are +that your favorite name has already been taken by another S3 user. +Usually a longer bucket name containing some random numbers, like +\code{19283712\_yourname\_s3ql}, will work better. + +If you do not already have one, you need to obtain an Amazon S3 +account from \href{http://aws.amazon.com/}{Amazon AWS}. The account is +free, you will pay only for the amount of storage that you actually +use. + +Note that the login and password for accessing S3 are not the user id +and password that you use to log into the Amazon Webpage, but the ``AWS +access key id'' and ``AWS secret access key'' shown under \href{https://aws-portal.amazon.com/gp/aws/developer/account/index.html?ie=UTF8\&action=access-key}{My +Account/Access Identifiers}. + +\begin{notice}{note}{Note:} +S3QL also allows you to use \href{http://aws.amazon.com/s3/\#protecting}{reduced redundancy storage} by using \code{s3rr://} +instead of \code{s3://} in the storage url. However, this not +recommended. The reason is a combination of three factors: +\begin{itemize} +\item {} +RRS has a relatively low reliability, on average you loose one +out of every ten-thousand objects a year. So you can expect to +occasionally loose some data. + +\item {} +When \code{fsck.s3ql} asks Amazon S3 for a list of the stored objects, +this list includes even those objects that have been lost. +Therefore \code{fsck.s3ql} \emph{can not detect lost objects} and lost data +will only become apparent when you try to actually read from a +file whose data has been lost. This is a (very unfortunate) +peculiarity of Amazon S3. + +\item {} +Due to the data de-duplication feature of S3QL, unnoticed lost +objects may cause subsequent data loss later in time (see {\hyperref[backends:on-backend-reliability]{On +Backend Reliability}} for details). + +\end{itemize} + +In other words, you should really only store an S3QL file system +using RRS if you know exactly what you are getting into. +\end{notice} + + +\section{The Local Backend} +\label{backends:the-local-backend} +The local backend stores file system data in a directory on your +computer. The storage URL for the local backend has the form +\code{local://\textless{}path\textgreater{}}. Note that you have to write three consecutive +slashes to specify an absolute path, e.g. \code{local:///var/archive}. + +The local backend provides read-after-write consistency. + + +\section{The SFTP Backend} +\label{backends:the-sftp-backend} +The SFTP backend uses the SFTP protocol, which is a file transfer +protocol similar to ftp, but uses an encrypted SSH connection. +It provides read-after-write consistency. + +Note that the SFTP backend is rather slow and has not been tested +as extensively as the S3 and Local backends. + +The storage URL for SFTP connections has the form + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{sftp://}\PYG{n+nv}{\textless{}host\textgreater{}}\PYG{g+ge}{[:port]}\PYG{l}{/}\PYG{n+nv}{\textless{}path\textgreater{}} +\end{Verbatim} + +The SFTP backend will always ask you for a password if you haven't +defined one in \code{\textasciitilde{}/.s3ql/authinfo}. However, public key authentication +is tried first and the password will only be used if the public key +authentication fails. + +The public and private keys will be read from the standard files in +\code{\textasciitilde{}/.ssh/}. Note that S3QL will refuse to connect to a computer with +unknown host key; to add the key to your local keyring you have to +establish a connection to that computer with the standard SSH command +line programs first. + + +\chapter{File System Creation} +\label{mkfs::doc}\label{mkfs:file-system-creation} +A S3QL file system is created with the \code{mkfs.s3ql} command. It has the +following syntax: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{mkfs.s3ql }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + +This command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}homedir \textless{}path\textgreater{}] +Directory for log files, cache and authentication +info. (default: \code{\textasciitilde{}/.s3ql)} +\item [-{-}debug \textless{}module\textgreater{}] +activate debugging output from \textless{}module\textgreater{}. Use \code{all} to +get debug messages from all modules. This option can +be specified multiple times. +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\item [-{-}ssl] +Use SSL when connecting to remote servers. This option +is not enabled by default, because for encrypted file +systems, all data is already encrypted anyway, and +authentication data is never transmitted in plaintext +even for unencrypted file systems. +\item [-{-}s3-location \textless{}name\textgreater{}] +Storage location for new S3 buckets. Allowed values: +\code{EU}, \code{us-west-1}, \code{ap-southeast-1}, or \code{us-standard}. +(default: EU) +\item [-L \textless{}name\textgreater{}] +Filesystem label +\item [-{-}blocksize \textless{}size\textgreater{}] +Maximum block size in KB (default: 10240) +\item [-{-}plain] +Create unencrypted file system. +\item [-{-}force] +Overwrite any existing data. +\end{optionlist} +\end{quote} + +Unless you have specified the \code{-{-}plain} option, \code{mkfs.s3ql} will ask you +to enter an encryption password. If you do not want to enter this +password every time that you mount the file system, you can store it +in the \code{\textasciitilde{}/.s3ql/authinfo} file, see {\hyperref[mount:bucket-pw]{\emph{Storing Encryption Passwords}}}. + + +\chapter{Managing Buckets} +\label{adm::doc}\label{adm:managing-buckets} +The \code{s3qladm} command performs various operations on S3QL buckets. +The file system contained in the bucket \emph{must not be mounted} when +using \code{s3qladm} or things will go wrong badly. + +The syntax is + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qladm }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}action\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}storage-url\textgreater{}} +\end{Verbatim} + +where \code{action} may be either of \textbf{passphrase}, +\textbf{upgrade}, \textbf{delete} or \textbf{download-metadata}. + +The \textbf{s3qladm} accepts the following general options, no +matter what specific action is being invoked: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug \textless{}module\textgreater{}] +activate debugging output from \textless{}module\textgreater{}. Use \code{all} to get +debug messages from all modules. This option can be +specified multiple times. +\item [-{-}quiet] +be really quiet +\item [-{-}homedir \textless{}path\textgreater{}] +Directory for log files, cache and authentication info. +(default: \code{\textasciitilde{}/.s3ql)} +\item [-{-}version] +just print program version and exit +\item [-{-}ssl] +Use SSL when connecting to remote servers. This option is +not enabled by default, because for encrypted file +systems, all data is already encrypted anyway, and +authentication data is never transmitted in plaintext +even for unencrypted file systems. +\end{optionlist} +\end{quote} + +Hint: run \code{s3qladm \textless{}action\textgreater{} -{-}help} to get help on the additional +arguments that the different actions take. + + +\section{Changing the Passphrase} +\label{adm:changing-the-passphrase} +To change the passphrase a bucket, use the \code{s3qladm} command: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qladm passphrase }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + +The passphrase can only be changed when the bucket is not mounted. + + +\section{Upgrading the file system} +\label{adm:upgrading-the-file-system} +If you have installed a new version of S3QL, it may sometimes be +necessary to upgrade the file system metadata as well. Note that in +this case the file system can no longer be accessed with older +versions of S3QL after the upgrade. + +During the upgrade you have to make sure that the command is not +interrupted, and that no one else tries to mount, check or upgrade the +file system at the same time. + +To upgrade a file system from the previous to the current revision, +execute + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qladm upgrade }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + + +\section{Deleting a file system} +\label{adm:deleting-a-file-system} +A file system can be deleted with: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qladm delete }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + +This physically deletes all the data and file system structures. + + +\section{Restoring Metadata Backups} +\label{adm:restoring-metadata-backups} +If the most-recent copy of the file system metadata has been damaged +irreparably, it is possible to restore one of the automatically +created backup copies. + +The command + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qladm download-metadata }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + +will give you a list of the available metadata backups and allow you +to download them. This will create two new files in the current +directory, ending in \code{.db} and \code{.params}. To actually use the +downloaded backup, you need to move these files into the \code{\textasciitilde{}/.s3ql/} +directory and run \code{fsck.s3ql}. + +\begin{notice}{warning}{Warning:} +You should probably not use this functionality without having asked +for help on the mailing list first (see {\hyperref[resources:resources]{\emph{Further Resources / Getting Help}}}). +\end{notice} + + +\chapter{Mounting} +\label{mount:mounting}\label{mount::doc} +A S3QL file system is mounted with the \code{mount.s3ql} command. It has +the following syntax: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{mount.s3ql }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}storage url\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}mountpoint\textgreater{}} +\end{Verbatim} + +\begin{notice}{note}{Note:} +S3QL is not a network file system like \href{http://en.wikipedia.org/wiki/Network\_File\_System\_\%28protocol\%29}{NFS} +or \href{http://en.wikipedia.org/wiki/CIFS}{CIFS}. It can only be +mounted on one computer at a time. +\end{notice} + +This command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}homedir \textless{}path\textgreater{}] +Directory for log files, cache and authentication +info. (default: \code{\textasciitilde{}/.s3ql)} +\item [-{-}debug \textless{}module\textgreater{}] +activate debugging output from \textless{}module\textgreater{}. Use \code{all} to +get debug messages from all modules. This option can +be specified multiple times. +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\item [-{-}ssl] +Use SSL when connecting to remote servers. This option +is not enabled by default, because for encrypted file +systems, all data is already encrypted anyway, and +authentication data is never transmitted in plaintext +even for unencrypted file systems. +\item [-{-}cachesize \textless{}size\textgreater{}] +Cache size in kb (default: 102400 (100 MB)). Should be +at least 10 times the blocksize of the filesystem, +otherwise an object may be retrieved and written +several times during a single write() or read() +operation. +\item [-{-}max-cache-entries \textless{}num\textgreater{}] +Maximum number of entries in cache (default: 768). +Each cache entry requires one file descriptor, so if +you increase this number you have to make sure that +your process file descriptor limit (as set with +\code{ulimit -n}) is high enough (at least the number of +cache entries + 100). +\item [-{-}allow-other] +Normally, only the user who called \code{mount.s3ql} can +access the mount point. This user then also has full +access to it, independent of individual file +permissions. If the \code{-{-}allow-other} option is +specified, other users can access the mount point as +well and individual file permissions are taken into +account for all users. +\item [-{-}allow-root] +Like \code{-{-}allow-other}, but restrict access to the +mounting user and the root user. +\item [-{-}fg] +Do not daemonize, stay in foreground +\item [-{-}single] +Run in single threaded mode. If you don't understand +this, then you don't need it. +\item [-{-}upstart] +Stay in foreground and raise SIGSTOP once mountpoint +is up. +\item [-{-}profile] +Create profiling information. If you don't understand +this, then you don't need it. +\item [-{-}compress \textless{}name\textgreater{}] +Compression algorithm to use when storing new data. +Allowed values: \code{lzma}, \code{bzip2}, \code{zlib}, none. +(default: \code{lzma}) +\item [-{-}metadata-upload-interval \textless{}seconds\textgreater{}] +Interval in seconds between complete metadata uploads. +Set to 0 to disable. Default: 24h. +\item [-{-}compression-threads \textless{}no\textgreater{}] +Number of parallel compression and encryption threads +to use (default: 1). +\end{optionlist} +\end{quote} + + +\section{Storing Encryption Passwords} +\label{mount:bucket-pw}\label{mount:storing-encryption-passwords} +If you are trying to mount an encrypted bucket, \code{mount.s3ql} will first +try to read the password from the \code{.s3ql/authinfo} file (the same file +that is used to read the backend authentication data) and prompt the +user to enter the password only if this fails. + +The \code{authinfo} entries to specify bucket passwords are of the form + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{storage-url }\PYG{n+nv}{\textless{}storage-url\textgreater{}}\PYG{l}{ password }\PYG{n+nv}{\textless{}password\textgreater{}} +\end{Verbatim} + +So to always use the password \code{topsecret} when mounting \code{s3://joes\_bucket}, +the entry would be + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{storage-url s3://joes\PYGZus{}bucket password topsecret} +\end{Verbatim} + +\begin{notice}{note}{Note:} +If you are using the local backend, the storage url will +always be converted to an absolute path. So if you are in the +\code{/home/john} directory and try to mount \code{local://bucket}, the matching +\code{authinfo} entry has to have a storage url of +\code{local:///home/john/bucket}. +\end{notice} + + +\section{Compression Algorithms} +\label{mount:compression-algorithms} +S3QL supports three compression algorithms, LZMA, Bzip2 and zlib (with +LZMA being the default). The compression algorithm can be specified +freely whenever the file system is mounted, since it affects only the +compression of new data blocks. + +Roughly speaking, LZMA is slower but achieves better compression +ratios than Bzip2, while Bzip2 in turn is slower but achieves better +compression ratios than zlib. + +For maximum file system performance, the best algorithm therefore +depends on your network connection speed: the compression algorithm +should be fast enough to saturate your network connection. + +To find the optimal algorithm for your system, S3QL ships with a +program called \code{benchmark.py} in the \code{contrib} directory. You should +run this program on a file that has a size that is roughly equal to +the block size of your file system and has similar contents. It will +then determine the compression speeds for the different algorithms and +the upload speeds for the specified backend and recommend the best +algorithm that is fast enough to saturate your network connection. + +Obviously you should make sure that there is little other system load +when you run \code{benchmark.py} (i.e., don't compile software or encode +videos at the same time). + + +\section{Parallel Compression} +\label{mount:parallel-compression} +If you are running S3QL on a system with multiple cores, you might +want to set \code{-{-}compression-threads} to a value bigger than one. This +will instruct S3QL to compress and encrypt several blocks at the same +time. + +If you want to do this in combination with using the LZMA compression +algorithm, you should keep an eye on memory usage though. Every +LZMA compression threads requires about 200 MB of RAM. + +\begin{notice}{note}{Note:} +To determine the optimal compression algorithm for your network +connection when using multiple threads, you can pass the +\code{-{-}compression-threads} option to \code{contrib/benchmark.py}. +\end{notice} + + +\section{Notes about Caching} +\label{mount:notes-about-caching} +S3QL maintains a local cache of the file system data to speed up +access. The cache is block based, so it is possible that only parts of +a file are in the cache. + + +\subsection{Maximum Number of Cache Entries} +\label{mount:maximum-number-of-cache-entries} +The maximum size of the cache can be configured with the \code{-{-}cachesize} +option. In addition to that, the maximum number of objects in the +cache is limited by the \code{-{-}max-cache-entries} option, so it is +possible that the cache does not grow up to the maximum cache size +because the maximum number of cache elements has been reached. The +reason for this limit is that each cache entry requires one open +file descriptor, and Linux distributions usually limit the total +number of file descriptors per process to about a thousand. + +If you specify a value for \code{-{-}max-cache-entries}, you should therefore +make sure to also configure your system to increase the maximum number +of open file handles. This can be done temporarily with the \code{umask -n} +command. The method to permanently change this limit system-wide +depends on your distribution. + + +\subsection{Cache Flushing and Expiration} +\label{mount:cache-flushing-and-expiration} +S3QL flushes changed blocks in the cache to the backend whenever a block +has not been accessed for at least 10 seconds. Note that when a block is +flushed, it still remains in the cache. + +Cache expiration (i.e., removal of blocks from the cache) is only done +when the maximum cache size is reached. S3QL always expires the least +recently used blocks first. + + +\section{Automatic Mounting} +\label{mount:automatic-mounting} +If you want to mount and umount an S3QL file system automatically at +system startup and shutdown, you should do so with one dedicated S3QL +init script for each S3QL file system. + +If your system is using upstart, an appropriate job can be defined +as follows (and should be placed in \code{/etc/init/}): + +\begin{Verbatim}[commandchars=\\\{\},numbers=left,firstnumber=1,stepnumber=1] +\PYG{l}{description "S3QL Backup File System"} +\PYG{l}{author "Nikolaus Rath }\PYG{n+nv}{\textless{}Nikolaus@rath.org\textgreater{}}\PYG{l}{"} + +\PYG{l}{\PYGZsh{} This assumes that eth0 provides your internet connection} +\PYG{l}{start on (filesystem and net-device-up IFACE=eth0)} +\PYG{l}{stop on runlevel }\PYG{g+ge}{[016]} + +\PYG{l}{env BUCKET="s3://my-backup-bla"} +\PYG{l}{env MOUNTPOINT="/mnt/backup"} + +\PYG{l}{expect stop} + +\PYG{l}{script} +\PYG{l}{ \PYGZsh{} Redirect stdout and stderr into the system log} +\PYG{l}{ DIR=\PYGZdl{}(mktemp -d)} +\PYG{l}{ mkfifo "\PYGZdl{}DIR/LOG\PYGZus{}FIFO"} +\PYG{l}{ logger -t s3ql -p local0.info }\PYG{n+nv}{\textless{} "\PYGZdl{}DIR/LOG\PYGZus{}FIFO" \&} +\PYG{n+nv}{ exec \textgreater{}}\PYG{l}{ "\PYGZdl{}DIR/LOG\PYGZus{}FIFO"} +\PYG{l}{ exec 2\textgreater{}\&1} +\PYG{l}{ rm -rf "\PYGZdl{}DIR"} + +\PYG{l}{ \PYGZsh{} Check and mount file system} +\PYG{l}{ fsck.s3ql --batch "\PYGZdl{}BUCKET"} +\PYG{l}{ exec mount.s3ql --upstart "\PYGZdl{}BUCKET" "\PYGZdl{}MOUNTPOINT"} +\PYG{l}{end script} + +\PYG{l}{pre-stop script} +\PYG{l}{ umount.s3ql "\PYGZdl{}MOUNTPOINT"} +\PYG{l}{end script} +\end{Verbatim} + +\begin{notice}{note}{Note:} +In principle, it is also possible to automatically mount an S3QL +file system with an appropriate entry in \code{/etc/fstab}. However, +this is not recommended for several reasons: +\begin{itemize} +\item {} +file systems mounted in \code{/etc/fstab} will be unmounted with the +\code{umount} command, so your system will not wait until all data has +been uploaded but shutdown (or restart) immediately (this is a +FUSE limitation, see \href{http://code.google.com/p/s3ql/issues/detail?id=159}{issue 159}). + +\item {} +There is no way to tell the system that mounting S3QL requires a +Python interpreter to be available, so it may attempt to run +\code{mount.s3ql} before it has mounted the volume containing the +Python interpreter. + +\item {} +There is no standard way to tell the system that internet +connection has to be up before the S3QL file system can be +mounted. + +\end{itemize} +\end{notice} + + +\chapter{Advanced S3QL Features} +\label{special:advanced-s3ql-features}\label{special::doc} + +\section{Snapshotting and Copy-on-Write} +\label{special:snapshotting-and-copy-on-write}\label{special:s3qlcp} +The command \code{s3qlcp} can be used to duplicate a directory tree without +physically copying the file contents. This is possible due to the data +de-duplication feature of S3QL. + +The syntax of \code{s3qlcp} is: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlcp }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}src\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}target\textgreater{}} +\end{Verbatim} + +This will replicate the contents of the directory \code{\textless{}src\textgreater{}} in the +directory \code{\textless{}target\textgreater{}}. \code{\textless{}src\textgreater{}} has to be an existing directory and +\code{\textless{}target\textgreater{}} must not exist. Moreover, both directories have to be +within the same S3QL file system. + +The replication will not take any additional space. Only if one of +directories is modified later on, the modified data will take +additional storage space. + +\code{s3qlcp} can only be called by the user that mounted the file system +and (if the file system was mounted with \code{-{-}allow-other} or \code{-{-}allow-root}) +the root user. This limitation might be removed in the future (see \href{http://code.google.com/p/s3ql/issues/detail?id=155}{issue 155}). + +Note that: +\begin{itemize} +\item {} +After the replication, both source and target directory will still +be completely ordinary directories. You can regard \code{\textless{}src\textgreater{}} as a +snapshot of \code{\textless{}target\textgreater{}} or vice versa. However, the most common +usage of \code{s3qlcp} is to regularly duplicate the same source +directory, say \code{documents}, to different target directories. For a +e.g. monthly replication, the target directories would typically be +named something like \code{documents\_Januray} for the replication in +January, \code{documents\_February} for the replication in February etc. +In this case it is clear that the target directories should be +regarded as snapshots of the source directory. + +\item {} +Exactly the same effect could be achieved by an ordinary copy +program like \code{cp -a}. However, this procedure would be orders of +magnitude slower, because \code{cp} would have to read every file +completely (so that S3QL had to fetch all the data over the network +from the backend) before writing them into the destination folder. + +\item {} +Before starting with the replication, S3QL has to flush the local +cache. So if you just copied lots of new data into the file system +that has not yet been uploaded, replication will take longer than +usual. + +\end{itemize} + + +\subsection{Snapshotting vs Hardlinking} +\label{special:snapshotting-vs-hardlinking} +Snapshot support in S3QL is inspired by the hardlinking feature that +is offered by programs like \href{http://www.samba.org/rsync}{rsync} or +\href{http://savannah.nongnu.org/projects/storebackup}{storeBackup}. +These programs can create a hardlink instead of copying a file if an +identical file already exists in the backup. However, using hardlinks +has two large disadvantages: +\begin{itemize} +\item {} +backups and restores always have to be made with a special program +that takes care of the hardlinking. The backup must not be touched +by any other programs (they may make changes that inadvertently +affect other hardlinked files) + +\item {} +special care needs to be taken to handle files which are already +hardlinked (the restore program needs to know that the hardlink was +not just introduced by the backup program to safe space) + +\end{itemize} + +S3QL snapshots do not have these problems, and they can be used with +any backup program. + + +\section{Getting Statistics} +\label{special:s3qlstat}\label{special:getting-statistics} +You can get more information about a mounted S3QL file system with the +\code{s3qlstat} command. It has the following syntax: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlstat }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}mountpoint\textgreater{}} +\end{Verbatim} + +Probably the most interesting numbers are the total size of your data, +the total size after duplication, and the final size after +de-duplication and compression. + +\code{s3qlstat} can only be called by the user that mounted the file system +and (if the file system was mounted with \code{-{-}allow-other} or \code{-{-}allow-root}) +the root user. This limitation might be removed in the future (see \href{http://code.google.com/p/s3ql/issues/detail?id=155}{issue 155}). + +For a full list of available options, run \code{s3qlstat -{-}help}. + + +\section{Immutable Trees} +\label{special:immutable-trees}\label{special:s3qllock} +The command \textbf{s3qllock} can be used to make a directory tree +immutable. Immutable trees can no longer be changed in any way +whatsoever. You can not add new files or directories and you can not +change or delete existing files and directories. The only way to get +rid of an immutable tree is to use the \textbf{s3qlrm} command (see +below). + +For example, to make the directory tree beneath the directory +\code{2010-04-21} immutable, execute + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qllock 2010-04-21} +\end{Verbatim} + +Immutability is a feature designed for backups. Traditionally, backups +have been made on external tape drives. Once a backup was made, the +tape drive was removed and locked somewhere in a shelf. This has the +great advantage that the contents of the backup are now permanently +fixed. Nothing (short of physical destruction) can change or delete +files in the backup. + +In contrast, when backing up into an online storage system like S3QL, +all backups are available every time the file system is mounted. +Nothing prevents a file in an old backup from being changed again +later on. In the worst case, this may make your entire backup system +worthless. Imagine that your system gets infected by a nasty virus +that simply deletes all files it can find -- if the virus is active +while the backup file system is mounted, the virus will destroy all +your old backups as well! + +Even if the possibility of a malicious virus or trojan horse is +excluded, being able to change a backup after it has been made is +generally not a good idea. A common S3QL use case is to keep the file +system mounted at all times and periodically create backups with +\textbf{rsync -a}. This allows every user to recover her files from a +backup without having to call the system administrator. However, this +also allows every user to accidentally change or delete files \emph{in} one +of the old backups. + +Making a backup immutable protects you against all these problems. +Unless you happen to run into a virus that was specifically programmed +to attack S3QL file systems, backups can be neither deleted nor +changed after they have been made immutable. + + +\section{Fast Recursive Removal} +\label{special:s3qlrm}\label{special:fast-recursive-removal} +The \code{s3qlrm} command can be used to recursively delete files and +directories on an S3QL file system. Although \code{s3qlrm} is faster than +using e.g. \code{rm -r}, the main reason for its existence is that it +allows you to delete immutable trees as well. The syntax is rather +simple: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlrm }\PYG{n+nv}{\textless{}directory\textgreater{}} +\end{Verbatim} + +Be warned that there is no additional confirmation. The directory will +be removed entirely and immediately. + + +\section{Runtime Configuration} +\label{special:runtime-configuration}\label{special:s3qlctrl} +The \code{s3qlctrl} can be used to control a mounted S3QL file system. Its +syntax is + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlctrl }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}action\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}mountpoint\textgreater{}}\PYG{l}{ ...} +\end{Verbatim} + +\code{\textless{}mountpoint\textgreater{}} must be the location of a mounted S3QL file system. +For a list of valid options, run \code{s3qlctrl -{-}help}. \code{\textless{}action\textgreater{}} +may be either of: +\begin{quote} +\begin{quote}\begin{description} +\item[{flushcache}] \leavevmode +Flush file system cache. The command blocks until the cache has +been flushed. + +\item[{log}] \leavevmode +Change log level. + +\item[{cachesize}] \leavevmode +Change file system cache size. + +\item[{upload-meta}] \leavevmode +Trigger a metadata upload. + +\end{description}\end{quote} +\end{quote} + + +\chapter{Unmounting} +\label{umount::doc}\label{umount:unmounting} +To unmount an S3QL file system, use the command: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{umount.s3ql }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}mountpoint\textgreater{}} +\end{Verbatim} + +This will block until all data has been committed to the storage +backend. + +Only the user who mounted the file system with \textbf{mount.s3ql} +is able to unmount it again. If you are root and want to unmount an +S3QL file system mounted by an ordinary user, you have to use the +\textbf{fusermount -u} or \textbf{umount} command instead. Note +that these commands do not block until all data has been uploaded, so +if you use them instead of \code{umount.s3ql} then you should manually wait +for the \code{mount.s3ql} process to terminate before shutting down the +system. + +The \textbf{umount.s3ql} command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug] +activate debugging output +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\item [-{-}lazy, -z] +Lazy umount. Detaches the file system immediately, even if +there are still open files. The data will be uploaded in the +background once all open files have been closed. +\end{optionlist} +\end{quote} + +If, for some reason, the \code{umount.sql} command does not work, the file +system can also be unmounted with \code{fusermount -u -z}. Note that this +command will return immediately and the file system may continue to +upload data in the background for a while longer. + + +\chapter{Checking for Errors} +\label{fsck:checking-for-errors}\label{fsck::doc} +If, for some reason, the filesystem has not been correctly unmounted, +or if you suspect that there might be errors, you should run the +\code{fsck.s3ql} utility. It has the following syntax: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{fsck.s3ql }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + +This command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}homedir \textless{}path\textgreater{}] +Directory for log files, cache and authentication info. +(default: \code{\textasciitilde{}/.s3ql)} +\item [-{-}debug \textless{}module\textgreater{}] +activate debugging output from \textless{}module\textgreater{}. Use \code{all} to get +debug messages from all modules. This option can be +specified multiple times. +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\item [-{-}ssl] +Use SSL when connecting to remote servers. This option is +not enabled by default, because for encrypted file +systems, all data is already encrypted anyway, and +authentication data is never transmitted in plaintext even +for unencrypted file systems. +\item [-{-}batch] +If user input is required, exit without prompting. +\item [-{-}force] +Force checking even if file system is marked clean. +\end{optionlist} +\end{quote} + + +\chapter{Contributed Programs} +\label{contrib:contributed-programs}\label{contrib::doc} +S3QL comes with a few contributed programs that are not part of the +core distribution (and are therefore not installed automatically by +default), but which may nevertheless be useful. These programs are in +the \code{contrib} directory of the source distribution or in +\code{/usr/share/doc/s3ql/contrib} if you installed S3QL from a package. + + +\section{benchmark.py} +\label{contrib:benchmark-py} +This program measures your uplink bandwidth and compression speed and +recommends a compression algorithm for optimal throughput. + + +\section{s3\_copy.py} +\label{contrib:s3-copy-py} +This program physically duplicates Amazon S3 bucket. It can be used to +migrate buckets to a different storage region or storage class +(standard or reduced redundancy). + + +\section{pcp.py} +\label{contrib:pcp-py}\label{contrib:pcp} +\code{pcp.py} is a wrapper program that starts several rsync processes to +copy directory trees in parallel. This is important because +transferring files in parallel significantly enhances performance when +copying data from an S3QL file system (see {\hyperref[tips:copy-performance]{\emph{Permanently mounted backup file system}}} for +details). + +To recursively copy the directory \code{/mnt/home-backup} into +\code{/home/joe} using 8 parallel processes and preserving permissions, +you would execute + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{pcp.py -a --processes=8 /mnt/home-backup/ /home/joe} +\end{Verbatim} + + +\section{s3\_backup.sh} +\label{contrib:s3-backup-sh} +This is an example script that demonstrates how to set up a simple but +powerful backup solution using S3QL and \href{http://samba.org/rsync}{rsync}. + +The \code{s3\_backup.sh} script automates the following steps: +\begin{enumerate} +\item {} +Mount the file system + +\item {} +Replicate the previous backup with {\hyperref[special:s3qlcp]{\emph{s3qlcp}}} + +\item {} +Update the new copy with the data from the backup source using rsync + +\item {} +Make the new backup immutable with {\hyperref[special:s3qllock]{\emph{s3qllock}}} + +\item {} +Delete old backups that are no longer needed + +\item {} +Unmount the file system + +\end{enumerate} + +The backups are stored in directories of the form +\code{YYYY-MM-DD\_HH:mm:SS} and the {\hyperref[contrib:expire-backups-py]{expire\_backups.py}} command is used to +delete old backups. + + +\section{expire\_backups.py} +\label{contrib:expire-backups-py} +\textbf{expire\_backups.py} is a program to intelligently remove old +backups that are no longer needed. + +To define what backups you want to keep for how long, you define a +number of \emph{age ranges}. \textbf{expire\_backups} ensures that you +will have at least one backup in each age range at all times. It will +keep exactly as many backups as are required for that and delete any +backups that become redundant. + +Age ranges are specified by giving a list of range boundaries in terms +of backup cycles. Every time you create a new backup, the existing +backups age by one cycle. + +Example: when \textbf{expire\_backups} is called with the age range +definition \code{1 3 7 14 31}, it will guarantee that you always have the +following backups available: +\begin{enumerate} +\item {} +A backup that is 0 to 1 cycles old (i.e, the most recent backup) + +\item {} +A backup that is 1 to 3 cycles old + +\item {} +A backup that is 3 to 7 cycles old + +\item {} +A backup that is 7 to 14 cycles old + +\item {} +A backup that is 14 to 31 cycles old + +\end{enumerate} + +\begin{notice}{note}{Note:} +If you do backups in fixed intervals, then one cycle will be +equivalent to the backup interval. The advantage of specifying the +age ranges in terms of backup cycles rather than days or weeks is +that it allows you to gracefully handle irregular backup intervals. +Imagine that for some reason you do not turn on your computer for +one month. Now all your backups are at least a month old, and if you +had specified the above backup strategy in terms of absolute ages, +they would all be deleted! Specifying age ranges in terms of backup +cycles avoids these sort of problems. +\end{notice} + +\textbf{expire\_backups} usage is simple. It requires backups to have +names of the forms \code{year-month-day\_hour:minute:seconds} +(\code{YYYY-MM-DD\_HH:mm:ss}) and works on all backups in the current +directory. So for the above backup strategy, the correct invocation +would be: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{expire\PYGZus{}backups.py 1 3 7 14 31} +\end{Verbatim} + +When storing your backups on an S3QL file system, you probably want to +specify the \code{-{-}use-s3qlrm} option as well. This tells +\textbf{expire\_backups} to use the {\hyperref[special:s3qlrm]{\emph{s3qlrm}}} command to +delete directories. + +\textbf{expire\_backups} uses a ``state file'' to keep track which +backups are how many cycles old (since this cannot be inferred from +the dates contained in the directory names). The standard name for +this state file is \code{.expire\_backups.dat}. If this file gets +damaged or deleted, \textbf{expire\_backups} no longer knows the ages +of the backups and refuses to work. In this case you can use the +\code{-{-}reconstruct-state} option to try to reconstruct the state +from the backup dates. However, the accuracy of this reconstruction +depends strongly on how rigorous you have been with making backups (it +is only completely correct if the time between subsequent backups has +always been exactly the same), so it's generally a good idea not to +tamper with the state file. + +For a full list of available options, run \textbf{expire\_backups.py +--help}. + + +\section{s3ql.conf} +\label{contrib:s3ql-conf} +\code{s3ql.conf} is an example upstart job definition file. It defines a +job that automatically mounts an S3QL file system on system start, and +properly unmounts it when the system is shut down. + + +\chapter{Tips \& Tricks} +\label{tips:tips-tricks}\label{tips::doc} + +\section{Permanently mounted backup file system} +\label{tips:copy-performance}\label{tips:permanently-mounted-backup-file-system} +If you use S3QL as a backup file system, it can be useful to mount the +file system permanently (rather than just mounting it for a backup and +unmounting it afterwards). Especially if your file system becomes +large, this saves you long mount- and unmount times if you only want +to restore a single file. + +If you decide to do so, you should make sure to +\begin{itemize} +\item {} +Use {\hyperref[special:s3qllock]{\emph{s3qllock}}} to ensure that backups are immutable +after they have been made. + +\item {} +Call {\hyperref[special:s3qlctrl]{\emph{s3qlctrl upload-meta}}} right after a every +backup to make sure that the newest metadata is stored safely (if +you do backups often enough, this may also allow you to set the +\code{-{-}metadata-upload-interval} option of \textbf{mount.s3ql} +to zero). + +\end{itemize} + + +\section{Improving copy performance} +\label{tips:improving-copy-performance} +If you want to copy a lot of smaller files \emph{from} an S3QL file system +(e.g. for a system restore) you will probably notice that the +performance is rather bad. + +The reason for this is intrinsic to the way S3QL works. Whenever you +read a file, S3QL first has to retrieve this file over the network +from the storage backend. This takes a minimum amount of time (the +network latency), no matter how big or small the file is. So when you +copy lots of small files, 99\% of the time is actually spend waiting +for network data. + +Theoretically, this problem is easy to solve: you just have to copy +several files at the same time. In practice, however, almost all unix +utilities (\code{cp}, \code{rsync}, \code{tar} and friends) insist on copying +data one file at a time. This makes a lot of sense when copying data +on the local hard disk, but in case of S3QL this is really +unfortunate. + +The best workaround that has been found so far is to copy files by +starting several rsync processes at once and use exclusion rules to +make sure that they work on different sets of files. + +For example, the following script will start 3 rsync instances. The +first instance handles all filenames starting with a-f, the second the +filenames from g-l and the third covers the rest. The \code{+ */} rule +ensures that every instance looks into all directories. + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{c}{\PYGZsh{}!/bin/bash} + +\PYG{l}{RSYNC\PYGZus{}ARGS="-aHv /mnt/s3ql/ /home/restore/"} + +\PYG{l}{rsync -f "+ */" -f "-! }\PYG{g+ge}{[a-f]}\PYG{l}{*" \PYGZdl{}RSYNC\PYGZus{}ARGS \&} +\PYG{l}{rsync -f "+ */" -f "-! }\PYG{g+ge}{[g-l]}\PYG{l}{*" \PYGZdl{}RSYNC\PYGZus{}ARGS \&} +\PYG{l}{rsync -f "+ */" -f "- }\PYG{g+ge}{[a-l]}\PYG{l}{*" \PYGZdl{}RSYNC\PYGZus{}ARGS \&} + +\PYG{l}{wait} +\end{Verbatim} + +The optimum number of parallel processes depends on your network +connection and the size of the files that you want to transfer. +However, starting about 10 processes seems to be a good compromise +that increases performance dramatically in almost all situations. + +S3QL comes with a script named \code{pcp.py} in the \code{contrib} directory +that can be used to transfer files in parallel without having to write +an explicit script first. See the description of {\hyperref[contrib:pcp]{\emph{pcp.py}}} for +details. + + +\chapter{Known Issues} +\label{issues:known-issues}\label{issues::doc}\begin{itemize} +\item {} +S3QL is rather slow when an application tries to write data in +unreasonably small chunks. If a 1 MB file is copied in chunks of 1 +KB, this will take more than 10 times as long as when it's copied +with the (recommended) chunk size of 128 KB. + +This is a limitation of the FUSE library (which does not yet support +write caching) which will hopefully be addressed in some future FUSE +version. + +Most applications, including e.g. GNU \code{cp} and \code{rsync}, use +reasonably large buffers and are therefore not affected by this +problem and perform very efficient on S3QL file systems. + +However, if you encounter unexpectedly slow performance with a +specific program, this might be due to the program using very small +write buffers. Although this is not really a bug in the program, +it might be worth to ask the program's authors for help. + +\item {} +S3QL always updates file and directory access times as if the \code{relatime} +mount option has been specified: the access time (``atime'') is only updated +if it is currently earlier than either the status change time +(``ctime'') or modification time (``mtime''). + +\item {} +S3QL directories always have an \code{st\_nlink} value of 1. This may confuse +programs that rely on directories having \code{st\_nlink} values of \emph{(2 + +number of sub directories)}. + +Note that this is not a bug in S3QL. Including sub directories in +the \code{st\_nlink} value is a Unix convention, but by no means a +requirement. If an application blindly relies on this convention +being followed, then this is a bug in the application. + +A prominent example are early versions of GNU find, which required +the \code{-{-}noleaf} option to work correctly on S3QL file systems. This +bug has already been fixed in recent find versions. + +\item {} +In theory, S3QL is not fully compatible with NFS. Since S3QL does +not support \emph{inode generation numbers}, NFS clients may (once again, +in theory) accidentally read or write the wrong file in the +following situation: +\begin{enumerate} +\item {} +An S3QL file system is exported over NFS + +\item {} +NFS client 1 opens a file A + +\item {} +Another NFS client 2 (or the server itself) deletes file A (without +client 1 knowing about this) + +\item {} +A new file B is created by either of the clients or the server + +\item {} +NFS client 1 tries to read or write file A (which has actually already been deleted). + +\end{enumerate} + +In this situation it is possible that NFS client 1 actually writes +or reads the newly created file B instead. The chances of this are 1 +to (2\textasciicircum{}32 - \emph{n}) where \emph{n} is the total number of directory entries +in the S3QL file system (as displayed by \code{s3qlstat}). + +Luckily enough, as long as you have less than about 2 thousand +million directory entries (2\textasciicircum{}31), the chances for this are totally +irrelevant and you don't have to worry about it. + +\item {} +The \code{umount} and \code{fusermount -u} commands will \emph{not} block until all +data has been uploaded to the backend. (this is a FUSE limitation +that will hopefully be removed in the future, see \href{http://code.google.com/p/s3ql/issues/detail?id=159}{issue 159}). If you use +either command to unmount an S3QL file system, you have to take care +to explicitly wait for the \code{mount.s3ql} process to terminate before +you shut down or restart the system. Therefore it is generally not a +good idea to mount an S3QL file system in \code{/etc/fstab} (you should +use a dedicated init script instead). + +\item {} +S3QL relies on the backends not to run out of space. This is a given +for big storage providers like Amazon S3, but you may stumble upon +this if you store buckets e.g. on a small sftp server. + +If there is no space left in the backend, attempts to write more +data into the S3QL file system will fail and the file system will be +in an inconsistent state and require a file system check (and you +should make sure to make space available in the backend before +running the check). + +Unfortunately, there is no way to handle insufficient space in the +backend without leaving the file system inconsistent. Since +S3QL first writes data into the cache, it can no longer return an +error when it later turns out that the cache can not be committed to +the backend. + +\end{itemize} + + +\chapter{Manpages} +\label{man/index:manpages}\label{man/index::doc} +The man pages are installed with S3QL on your system and can be viewed +with the \textbf{man} command. For reference, they are also included +here in the User's Guide. + + +\section{The \textbf{mkfs.s3ql} command} +\label{man/mkfs:the-mkfs-s3ql-command}\label{man/mkfs::doc} + +\subsection{Synopsis} +\label{man/mkfs:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{mkfs.s3ql }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/mkfs:description} +The \textbf{mkfs.s3ql} command creates a new file system in the location +specified by \emph{storage url}. + +The form of the storage url depends on the backend that is used. The +following backends are supported: + + +\subsubsection{Amazon S3} +\label{man/mkfs:amazon-s3} +To store your file system in an Amazon S3 bucket, use a storage URL of +the form \code{s3://\textless{}bucketname\textgreater{}}. Bucket names must conform to the S3 Bucket +Name Restrictions. + + +\subsubsection{Local} +\label{man/mkfs:local} +The local backend stores file system data in a directory on your +computer. The storage URL for the local backend has the form +\code{local://\textless{}path\textgreater{}}. Note that you have to write three consecutive +slashes to specify an absolute path, e.g. \code{local:///var/archive}. + + +\subsubsection{SFTP} +\label{man/mkfs:sftp} +The storage URL for SFTP connections has the form + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{sftp://}\PYG{n+nv}{\textless{}host\textgreater{}}\PYG{g+ge}{[:port]}\PYG{l}{/}\PYG{n+nv}{\textless{}path\textgreater{}} +\end{Verbatim} + + +\subsection{Options} +\label{man/mkfs:options} +The \textbf{mkfs.s3ql} command accepts the following options. +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}homedir \textless{}path\textgreater{}] +Directory for log files, cache and authentication +info. (default: \code{\textasciitilde{}/.s3ql)} +\item [-{-}debug \textless{}module\textgreater{}] +activate debugging output from \textless{}module\textgreater{}. Use \code{all} to +get debug messages from all modules. This option can +be specified multiple times. +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\item [-{-}ssl] +Use SSL when connecting to remote servers. This option +is not enabled by default, because for encrypted file +systems, all data is already encrypted anyway, and +authentication data is never transmitted in plaintext +even for unencrypted file systems. +\item [-{-}s3-location \textless{}name\textgreater{}] +Storage location for new S3 buckets. Allowed values: +\code{EU}, \code{us-west-1}, \code{ap-southeast-1}, or \code{us-standard}. +(default: EU) +\item [-L \textless{}name\textgreater{}] +Filesystem label +\item [-{-}blocksize \textless{}size\textgreater{}] +Maximum block size in KB (default: 10240) +\item [-{-}plain] +Create unencrypted file system. +\item [-{-}force] +Overwrite any existing data. +\end{optionlist} +\end{quote} + + +\subsection{Files} +\label{man/mkfs:files} +Authentication data for backends and bucket encryption passphrases are +read from \code{authinfo} in \code{\textasciitilde{}/.s3ql} or the directory +specified with \code{-{-}homedir}. Log files are placed in the same +directory. + + +\subsection{Exit Status} +\label{man/mkfs:exit-status} +\textbf{mkfs.s3ql} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/mkfs:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{s3qladm} command} +\label{man/adm::doc}\label{man/adm:the-s3qladm-command} + +\subsection{Synopsis} +\label{man/adm:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qladm }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}action\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + +where \code{action} may be either of \textbf{passphrase}, +\textbf{upgrade}, \textbf{delete} or \textbf{download-metadata}. + + +\subsection{Description} +\label{man/adm:description} +The \textbf{s3qladm} command performs various operations on S3QL buckets. +The file system contained in the bucket \emph{must not be mounted} when +using \textbf{s3qladm} or things will go wrong badly. + +The form of the storage url depends on the backend that is used. The +following backends are supported: + + +\subsubsection{Amazon S3} +\label{man/adm:amazon-s3} +To store your file system in an Amazon S3 bucket, use a storage URL of +the form \code{s3://\textless{}bucketname\textgreater{}}. Bucket names must conform to the S3 Bucket +Name Restrictions. + + +\subsubsection{Local} +\label{man/adm:local} +The local backend stores file system data in a directory on your +computer. The storage URL for the local backend has the form +\code{local://\textless{}path\textgreater{}}. Note that you have to write three consecutive +slashes to specify an absolute path, e.g. \code{local:///var/archive}. + + +\subsubsection{SFTP} +\label{man/adm:sftp} +The storage URL for SFTP connections has the form + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{sftp://}\PYG{n+nv}{\textless{}host\textgreater{}}\PYG{g+ge}{[:port]}\PYG{l}{/}\PYG{n+nv}{\textless{}path\textgreater{}} +\end{Verbatim} + + +\subsection{Options} +\label{man/adm:options} +The \textbf{s3qladm} command accepts the following options. +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug \textless{}module\textgreater{}] +activate debugging output from \textless{}module\textgreater{}. Use \code{all} to get +debug messages from all modules. This option can be +specified multiple times. +\item [-{-}quiet] +be really quiet +\item [-{-}homedir \textless{}path\textgreater{}] +Directory for log files, cache and authentication info. +(default: \code{\textasciitilde{}/.s3ql)} +\item [-{-}version] +just print program version and exit +\item [-{-}ssl] +Use SSL when connecting to remote servers. This option is +not enabled by default, because for encrypted file +systems, all data is already encrypted anyway, and +authentication data is never transmitted in plaintext +even for unencrypted file systems. +\end{optionlist} +\end{quote} + +Hint: run \code{s3qladm \textless{}action\textgreater{} -{-}help} to get help on the additional +arguments that the different actions take. + + +\subsection{Actions} +\label{man/adm:actions} +The following actions may be specified: +\begin{description} +\item[{passphrase}] \leavevmode +Changes the encryption passphrase of the bucket. + +\item[{upgrade}] \leavevmode +Upgrade the file system contained in the bucket to the newest revision. + +\item[{delete}] \leavevmode +Delete the bucket and all its contents. + +\item[{download-metadata}] \leavevmode +Interactively download backups of the file system metadata. + +\end{description} + + +\subsection{Files} +\label{man/adm:files} +Authentication data for backends and bucket encryption passphrases are +read from \code{authinfo} in \code{\textasciitilde{}/.s3ql} or the directory +specified with \code{-{-}homedir}. Log files are placed in the same +directory. + + +\subsection{Exit Status} +\label{man/adm:exit-status} +\textbf{s3qladm} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/adm:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{mount.s3ql} command} +\label{man/mount::doc}\label{man/mount:the-mount-s3ql-command} + +\subsection{Synopsis} +\label{man/mount:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{mount.s3ql }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}storage url\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}mount point\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/mount:description} +The \textbf{mount.s3ql} command mounts the S3QL file system stored in \emph{storage +url} in the directory \emph{mount point}. + +The form of the storage url depends on the backend that is used. The +following backends are supported: + + +\subsubsection{Amazon S3} +\label{man/mount:amazon-s3} +To store your file system in an Amazon S3 bucket, use a storage URL of +the form \code{s3://\textless{}bucketname\textgreater{}}. Bucket names must conform to the S3 Bucket +Name Restrictions. + + +\subsubsection{Local} +\label{man/mount:local} +The local backend stores file system data in a directory on your +computer. The storage URL for the local backend has the form +\code{local://\textless{}path\textgreater{}}. Note that you have to write three consecutive +slashes to specify an absolute path, e.g. \code{local:///var/archive}. + + +\subsubsection{SFTP} +\label{man/mount:sftp} +The storage URL for SFTP connections has the form + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{sftp://}\PYG{n+nv}{\textless{}host\textgreater{}}\PYG{g+ge}{[:port]}\PYG{l}{/}\PYG{n+nv}{\textless{}path\textgreater{}} +\end{Verbatim} + + +\subsection{Options} +\label{man/mount:options} +The \textbf{mount.s3ql} command accepts the following options. +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}homedir \textless{}path\textgreater{}] +Directory for log files, cache and authentication +info. (default: \code{\textasciitilde{}/.s3ql)} +\item [-{-}debug \textless{}module\textgreater{}] +activate debugging output from \textless{}module\textgreater{}. Use \code{all} to +get debug messages from all modules. This option can +be specified multiple times. +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\item [-{-}ssl] +Use SSL when connecting to remote servers. This option +is not enabled by default, because for encrypted file +systems, all data is already encrypted anyway, and +authentication data is never transmitted in plaintext +even for unencrypted file systems. +\item [-{-}cachesize \textless{}size\textgreater{}] +Cache size in kb (default: 102400 (100 MB)). Should be +at least 10 times the blocksize of the filesystem, +otherwise an object may be retrieved and written +several times during a single write() or read() +operation. +\item [-{-}max-cache-entries \textless{}num\textgreater{}] +Maximum number of entries in cache (default: 768). +Each cache entry requires one file descriptor, so if +you increase this number you have to make sure that +your process file descriptor limit (as set with +\code{ulimit -n}) is high enough (at least the number of +cache entries + 100). +\item [-{-}allow-other] +Normally, only the user who called \code{mount.s3ql} can +access the mount point. This user then also has full +access to it, independent of individual file +permissions. If the \code{-{-}allow-other} option is +specified, other users can access the mount point as +well and individual file permissions are taken into +account for all users. +\item [-{-}allow-root] +Like \code{-{-}allow-other}, but restrict access to the +mounting user and the root user. +\item [-{-}fg] +Do not daemonize, stay in foreground +\item [-{-}single] +Run in single threaded mode. If you don't understand +this, then you don't need it. +\item [-{-}upstart] +Stay in foreground and raise SIGSTOP once mountpoint +is up. +\item [-{-}profile] +Create profiling information. If you don't understand +this, then you don't need it. +\item [-{-}compress \textless{}name\textgreater{}] +Compression algorithm to use when storing new data. +Allowed values: \code{lzma}, \code{bzip2}, \code{zlib}, none. +(default: \code{lzma}) +\item [-{-}metadata-upload-interval \textless{}seconds\textgreater{}] +Interval in seconds between complete metadata uploads. +Set to 0 to disable. Default: 24h. +\item [-{-}compression-threads \textless{}no\textgreater{}] +Number of parallel compression and encryption threads +to use (default: 1). +\end{optionlist} +\end{quote} + + +\subsection{Files} +\label{man/mount:files} +Authentication data for backends and bucket encryption passphrases are +read from \code{authinfo} in \code{\textasciitilde{}/.s3ql} or the directory +specified with \code{-{-}homedir}. Log files are placed in the same +directory. + + +\subsection{Exit Status} +\label{man/mount:exit-status} +\textbf{mount.s3ql} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/mount:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{s3qlstat} command} +\label{man/stat:the-s3qlstat-command}\label{man/stat::doc} + +\subsection{Synopsis} +\label{man/stat:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlstat }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}mountpoint\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/stat:description} +The \textbf{s3qlstat} command prints statistics about the S3QL file system mounted +at \code{mountpoint}. + +\textbf{s3qlstat} can only be called by the user that mounted the file system +and (if the file system was mounted with \code{-{-}allow-other} or +\code{-{-}allow-root}) the root user. This limitation might be +removed in the future (see \href{http://code.google.com/p/s3ql/issues/detail?id=155}{issue 155}). + + +\subsection{Options} +\label{man/stat:options} +The \textbf{s3qlstat} command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug] +activate debugging output +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\end{optionlist} +\end{quote} + + +\subsection{Exit Status} +\label{man/stat:exit-status} +\textbf{s3qlstat} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/stat:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{s3qlctrl} command} +\label{man/ctrl:the-s3qlctrl-command}\label{man/ctrl::doc} + +\subsection{Synopsis} +\label{man/ctrl:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlctrl }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}action\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}mountpoint\textgreater{}}\PYG{l}{ ...} +\end{Verbatim} + +where \code{action} may be either of \textbf{flushcache}, +\textbf{upload-meta}, \textbf{cachesize} or +\textbf{log-metadata}. + + +\subsection{Description} +\label{man/ctrl:description} +The \textbf{s3qlctrl} command performs various actions on the S3QL file system mounted +in \code{mountpoint}. + +The following actions may be specified: +\begin{description} +\item[{flushcache}] \leavevmode +Uploads all changed file data to the backend. + +\item[{upload-meta}] \leavevmode +Upload metadata to the backend. All file system operations will +block while a snapshot of the metadata is prepared for upload. + +\item[{cachesize}] \leavevmode +Changes the cache size of the file system. This action requires an +additional argument that specifies the new cache size in kB, so the +complete command line is: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlctrl }\PYG{g+ge}{[options]}\PYG{l}{ cachesize }\PYG{n+nv}{\textless{}mountpoint\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}new-cache-size\textgreater{}} +\end{Verbatim} + +\item[{log}] \leavevmode +Change the amount of information that is logged into +\code{\textasciitilde{}/.s3ql/mount.log} file. The complete syntax is: + +\begin{Verbatim}[commandchars=@\[\]] +s3qlctrl @PYGZlb[]options@PYGZrb[] log @textless[]mountpoint@textgreater[] @textless[]level@textgreater[] @PYGZlb[]@textless[]module@textgreater[] @PYGZlb[]@textless[]module@textgreater[] ...@PYGZrb[]@PYGZrb[] +\end{Verbatim} + +here \code{level} is the desired new log level and may be either of +\emph{debug}, \emph{info} or \emph{warn}. One or more \code{module} may only be +specified with the \emph{debug} level and allow to restrict the debug +output to just the listed modules. + +\end{description} + + +\subsection{Options} +\label{man/ctrl:options} +The \textbf{s3qlctrl} command also accepts the following options, no matter +what specific action is being invoked: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug] +activate debugging output +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\end{optionlist} +\end{quote} + +Hint: run \code{s3qlctrl \textless{}action\textgreater{} -{-}help} to get help on the additional +arguments that the different actions take. + + +\subsection{Exit Status} +\label{man/ctrl:exit-status} +\textbf{s3qlctrl} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/ctrl:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{s3qlcp} command} +\label{man/cp:the-s3qlcp-command}\label{man/cp::doc} + +\subsection{Synopsis} +\label{man/cp:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlcp }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}source-dir\textgreater{}}\PYG{l}{ }\PYG{n+nv}{\textless{}dest-dir\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/cp:description} +The \textbf{s3qlcp} command duplicates the directory tree \code{source-dir} +into \code{dest-dir} without physically copying the file contents. +Both source and destination must lie inside the same S3QL file system. + +The replication will not take any additional space. Only if one of +directories is modified later on, the modified data will take +additional storage space. + +\code{s3qlcp} can only be called by the user that mounted the file system +and (if the file system was mounted with \code{-{-}allow-other} or \code{-{-}allow-root}) +the root user. This limitation might be removed in the future (see \href{http://code.google.com/p/s3ql/issues/detail?id=155}{issue 155}). + +Note that: +\begin{itemize} +\item {} +After the replication, both source and target directory will still +be completely ordinary directories. You can regard \code{\textless{}src\textgreater{}} as a +snapshot of \code{\textless{}target\textgreater{}} or vice versa. However, the most common +usage of \code{s3qlcp} is to regularly duplicate the same source +directory, say \code{documents}, to different target directories. For a +e.g. monthly replication, the target directories would typically be +named something like \code{documents\_Januray} for the replication in +January, \code{documents\_February} for the replication in February etc. +In this case it is clear that the target directories should be +regarded as snapshots of the source directory. + +\item {} +Exactly the same effect could be achieved by an ordinary copy +program like \code{cp -a}. However, this procedure would be orders of +magnitude slower, because \code{cp} would have to read every file +completely (so that S3QL had to fetch all the data over the network +from the backend) before writing them into the destination folder. + +\item {} +Before starting with the replication, S3QL has to flush the local +cache. So if you just copied lots of new data into the file system +that has not yet been uploaded, replication will take longer than +usual. + +\end{itemize} + + +\subsubsection{Snapshotting vs Hardlinking} +\label{man/cp:snapshotting-vs-hardlinking} +Snapshot support in S3QL is inspired by the hardlinking feature that +is offered by programs like \href{http://www.samba.org/rsync}{rsync} or +\href{http://savannah.nongnu.org/projects/storebackup}{storeBackup}. +These programs can create a hardlink instead of copying a file if an +identical file already exists in the backup. However, using hardlinks +has two large disadvantages: +\begin{itemize} +\item {} +backups and restores always have to be made with a special program +that takes care of the hardlinking. The backup must not be touched +by any other programs (they may make changes that inadvertently +affect other hardlinked files) + +\item {} +special care needs to be taken to handle files which are already +hardlinked (the restore program needs to know that the hardlink was +not just introduced by the backup program to safe space) + +\end{itemize} + +S3QL snapshots do not have these problems, and they can be used with +any backup program. + + +\subsection{Options} +\label{man/cp:options} +The \textbf{s3qlcp} command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug] +activate debugging output +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\end{optionlist} +\end{quote} + + +\subsection{Exit Status} +\label{man/cp:exit-status} +\textbf{s3qlcp} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/cp:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{s3qlrm} command} +\label{man/rm::doc}\label{man/rm:the-s3qlrm-command} + +\subsection{Synopsis} +\label{man/rm:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qlrm }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}directory\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/rm:description} +The \textbf{s3qlrm} command recursively deletes files and directories on an +S3QL file system. Although \textbf{s3qlrm} is faster than using e.g. +\textbf{rm -r{}`}, the main reason for its existence is that it allows +you to delete immutable trees (which can be created with +\textbf{s3qllock}) as well. + +Be warned that there is no additional confirmation. The directory will +be removed entirely and immediately. + + +\subsection{Options} +\label{man/rm:options} +The \textbf{s3qlrm} command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug] +activate debugging output +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\end{optionlist} +\end{quote} + + +\subsection{Exit Status} +\label{man/rm:exit-status} +\textbf{s3qlrm} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/rm:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{s3qllock} command} +\label{man/lock:the-s3qllock-command}\label{man/lock::doc} + +\subsection{Synopsis} +\label{man/lock:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{s3qllock }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}directory\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/lock:description} +The \textbf{s3qllock} command makes a directory tree in an S3QL file +system immutable. Immutable trees can no longer be changed in any way +whatsoever. You can not add new files or directories and you can not +change or delete existing files and directories. The only way to get +rid of an immutable tree is to use the \textbf{s3qlrm} command. + + +\subsection{Rationale} +\label{man/lock:rationale} +Immutability is a feature designed for backups. Traditionally, backups +have been made on external tape drives. Once a backup was made, the +tape drive was removed and locked somewhere in a shelf. This has the +great advantage that the contents of the backup are now permanently +fixed. Nothing (short of physical destruction) can change or delete +files in the backup. + +In contrast, when backing up into an online storage system like S3QL, +all backups are available every time the file system is mounted. +Nothing prevents a file in an old backup from being changed again +later on. In the worst case, this may make your entire backup system +worthless. Imagine that your system gets infected by a nasty virus +that simply deletes all files it can find -- if the virus is active +while the backup file system is mounted, the virus will destroy all +your old backups as well! + +Even if the possibility of a malicious virus or trojan horse is +excluded, being able to change a backup after it has been made is +generally not a good idea. A common S3QL use case is to keep the file +system mounted at all times and periodically create backups with +\textbf{rsync -a}. This allows every user to recover her files from a +backup without having to call the system administrator. However, this +also allows every user to accidentally change or delete files \emph{in} one +of the old backups. + +Making a backup immutable protects you against all these problems. +Unless you happen to run into a virus that was specifically programmed +to attack S3QL file systems, backups can be neither deleted nor +changed after they have been made immutable. + + +\subsection{Options} +\label{man/lock:options} +The \textbf{s3qllock} command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug] +activate debugging output +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\end{optionlist} +\end{quote} + + +\subsection{Exit Status} +\label{man/lock:exit-status} +\textbf{s3qllock} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/lock:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{umount.s3ql} command} +\label{man/umount::doc}\label{man/umount:the-umount-s3ql-command} + +\subsection{Synopsis} +\label{man/umount:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{umount.s3ql }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}mount point\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/umount:description} +The \textbf{umount.s3ql} command unmounts the S3QL file system mounted in the +directory \emph{mount point} and blocks until all data has been uploaded to +the storage backend. + +Only the user who mounted the file system with \textbf{mount.s3ql} +is able to unmount it with \textbf{umount.s3ql}. If you are root and want to +unmount an S3QL file system mounted by an ordinary user, you have to +use the \textbf{fusermount -u} or \textbf{umount} command instead. +Note that these commands do not block until all data has been +uploaded, so if you use them instead of \textbf{umount.s3ql} then +you should manually wait for the \textbf{mount.s3ql} process to +terminate before shutting down the system. + + +\subsection{Options} +\label{man/umount:options} +The \textbf{umount.s3ql} command accepts the following options. +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}debug] +activate debugging output +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\item [-{-}lazy, -z] +Lazy umount. Detaches the file system immediately, even if +there are still open files. The data will be uploaded in the +background once all open files have been closed. +\end{optionlist} +\end{quote} + + +\subsection{Exit Status} +\label{man/umount:exit-status} +\textbf{umount.s3ql} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/umount:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{fsck.s3ql} command} +\label{man/fsck::doc}\label{man/fsck:the-fsck-s3ql-command} + +\subsection{Synopsis} +\label{man/fsck:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{fsck.s3ql }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}storage url\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/fsck:description} +The \textbf{mkfs.s3ql} command checks the new file system in the location +specified by \emph{storage url} for errors and attempts to repair any +problems. + +The form of the storage url depends on the backend that is used. The +following backends are supported: + + +\subsubsection{Amazon S3} +\label{man/fsck:amazon-s3} +To store your file system in an Amazon S3 bucket, use a storage URL of +the form \code{s3://\textless{}bucketname\textgreater{}}. Bucket names must conform to the S3 Bucket +Name Restrictions. + + +\subsubsection{Local} +\label{man/fsck:local} +The local backend stores file system data in a directory on your +computer. The storage URL for the local backend has the form +\code{local://\textless{}path\textgreater{}}. Note that you have to write three consecutive +slashes to specify an absolute path, e.g. \code{local:///var/archive}. + + +\subsubsection{SFTP} +\label{man/fsck:sftp} +The storage URL for SFTP connections has the form + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{sftp://}\PYG{n+nv}{\textless{}host\textgreater{}}\PYG{g+ge}{[:port]}\PYG{l}{/}\PYG{n+nv}{\textless{}path\textgreater{}} +\end{Verbatim} + + +\subsection{Options} +\label{man/fsck:options} +The \textbf{mkfs.s3ql} command accepts the following options. +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}homedir \textless{}path\textgreater{}] +Directory for log files, cache and authentication info. +(default: \code{\textasciitilde{}/.s3ql)} +\item [-{-}debug \textless{}module\textgreater{}] +activate debugging output from \textless{}module\textgreater{}. Use \code{all} to get +debug messages from all modules. This option can be +specified multiple times. +\item [-{-}quiet] +be really quiet +\item [-{-}version] +just print program version and exit +\item [-{-}ssl] +Use SSL when connecting to remote servers. This option is +not enabled by default, because for encrypted file +systems, all data is already encrypted anyway, and +authentication data is never transmitted in plaintext even +for unencrypted file systems. +\item [-{-}batch] +If user input is required, exit without prompting. +\item [-{-}force] +Force checking even if file system is marked clean. +\end{optionlist} +\end{quote} + + +\subsection{Files} +\label{man/fsck:files} +Authentication data for backends and bucket encryption passphrases are +read from \code{authinfo} in \code{\textasciitilde{}/.s3ql} or the directory +specified with \code{-{-}homedir}. Log files are placed in the same +directory. + + +\subsection{Exit Status} +\label{man/fsck:exit-status} +\textbf{mkfs.s3ql} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/fsck:see-also} +The S3QL homepage is at \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + +The full S3QL documentation should also be installed somewhere on your +system, conventional locations are \code{/usr/share/doc/s3ql} or +\code{/usr/local/doc/s3ql}. + + +\section{The \textbf{pcp} command} +\label{man/pcp:the-pcp-command}\label{man/pcp::doc} + +\subsection{Synopsis} +\label{man/pcp:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{pcp }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}source\textgreater{}}\PYG{l}{ }\PYG{g+ge}{[\textless{}source\textgreater{} ...]}\PYG{l}{ }\PYG{n+nv}{\textless{}destination\textgreater{}} +\end{Verbatim} + + +\subsection{Description} +\label{man/pcp:description} +The \textbf{pcp} command is a is a wrapper that starts several +\textbf{sync} processes to copy directory trees in parallel. This is +allows much better copying performance on file system that have +relatively high latency when retrieving individual files like S3QL. + + +\subsection{Options} +\label{man/pcp:options} +The \textbf{pcp} command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}quiet] +be really quiet +\item [-{-}debug] +activate debugging output +\item [-{-}version] +just print program version and exit +\item [-a] +Pass -aHAX option to rsync. +\item [-{-}processes \textless{}no\textgreater{}] +Number of rsync processes to use (default: 10). +\end{optionlist} +\end{quote} + + +\subsection{Exit Status} +\label{man/pcp:exit-status} +\textbf{pcp} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/pcp:see-also} +\textbf{pcp} is shipped as part of S3QL, \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + + +\section{The \textbf{expire\_backups} command} +\label{man/expire_backups::doc}\label{man/expire_backups:the-expire-backups-command} + +\subsection{Synopsis} +\label{man/expire_backups:synopsis} +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{expire\PYGZus{}backups }\PYG{g+ge}{[options]}\PYG{l}{ }\PYG{n+nv}{\textless{}age\textgreater{}}\PYG{l}{ }\PYG{g+ge}{[\textless{}age\textgreater{} ...]} +\end{Verbatim} + + +\subsection{Description} +\label{man/expire_backups:description} +The \textbf{expire\_backups} command intelligently remove old backups that are no +longer needed. + +To define what backups you want to keep for how long, you define a +number of \emph{age ranges}. \textbf{expire\_backups} ensures that you +will have at least one backup in each age range at all times. It will +keep exactly as many backups as are required for that and delete any +backups that become redundant. + +Age ranges are specified by giving a list of range boundaries in terms +of backup cycles. Every time you create a new backup, the existing +backups age by one cycle. + +Example: when \textbf{expire\_backups} is called with the age range +definition \code{1 3 7 14 31}, it will guarantee that you always have the +following backups available: +\begin{enumerate} +\item {} +A backup that is 0 to 1 cycles old (i.e, the most recent backup) + +\item {} +A backup that is 1 to 3 cycles old + +\item {} +A backup that is 3 to 7 cycles old + +\item {} +A backup that is 7 to 14 cycles old + +\item {} +A backup that is 14 to 31 cycles old + +\end{enumerate} + +\begin{notice}{note}{Note:} +If you do backups in fixed intervals, then one cycle will be +equivalent to the backup interval. The advantage of specifying the +age ranges in terms of backup cycles rather than days or weeks is +that it allows you to gracefully handle irregular backup intervals. +Imagine that for some reason you do not turn on your computer for +one month. Now all your backups are at least a month old, and if you +had specified the above backup strategy in terms of absolute ages, +they would all be deleted! Specifying age ranges in terms of backup +cycles avoids these sort of problems. +\end{notice} + +\textbf{expire\_backups} usage is simple. It requires backups to have +names of the forms \code{year-month-day\_hour:minute:seconds} +(\code{YYYY-MM-DD\_HH:mm:ss}) and works on all backups in the current +directory. So for the above backup strategy, the correct invocation +would be: + +\begin{Verbatim}[commandchars=\\\{\}] +\PYG{l}{expire\PYGZus{}backups.py 1 3 7 14 31} +\end{Verbatim} + +When storing your backups on an S3QL file system, you probably want to +specify the \code{-{-}use-s3qlrm} option as well. This tells +\textbf{expire\_backups} to use the {\hyperref[special:s3qlrm]{\emph{s3qlrm}}} command to +delete directories. + +\textbf{expire\_backups} uses a ``state file'' to keep track which +backups are how many cycles old (since this cannot be inferred from +the dates contained in the directory names). The standard name for +this state file is \code{.expire\_backups.dat}. If this file gets +damaged or deleted, \textbf{expire\_backups} no longer knows the ages +of the backups and refuses to work. In this case you can use the +\code{-{-}reconstruct-state} option to try to reconstruct the state +from the backup dates. However, the accuracy of this reconstruction +depends strongly on how rigorous you have been with making backups (it +is only completely correct if the time between subsequent backups has +always been exactly the same), so it's generally a good idea not to +tamper with the state file. + + +\subsection{Options} +\label{man/expire_backups:options} +The \textbf{expire\_backups} command accepts the following options: +\begin{quote} +\begin{optionlist}{3cm} +\item [-{-}quiet] +be really quiet +\item [-{-}debug] +activate debugging output +\item [-{-}version] +just print program version and exit +\item [-{-}state \textless{}file\textgreater{}] +File to save state information in (default: +''.expire\_backups.dat'') +\item [-n] +Dry run. Just show which backups would be deleted. +\item [-{-}reconstruct-state] +Try to reconstruct a missing state file from backup +dates. +\item [-{-}use-s3qlrm] +Use \code{s3qlrm} command to delete backups. +\end{optionlist} +\end{quote} + + +\subsection{Exit Status} +\label{man/expire_backups:exit-status} +\textbf{expire\_backups} returns exit code 0 if the operation succeeded and 1 if some +error occured. + + +\subsection{See Also} +\label{man/expire_backups:see-also} +\textbf{expire\_backups} is shipped as part of S3QL, \href{http://code.google.com/p/s3ql/}{http://code.google.com/p/s3ql/}. + + +\chapter{Further Resources / Getting Help} +\label{resources::doc}\label{resources:further-resources-getting-help}\label{resources:resources} +If you have questions or problems with S3QL that you weren't able to +resolve with this manual, you might want to consider the following other resources: +\begin{itemize} +\item {} +The \href{http://code.google.com/p/s3ql/w/list}{S3QL Wiki} + +\item {} +The \href{http://code.google.com/p/s3ql/wiki/FAQ}{S3QL FAQ} + +\item {} +The \href{http://groups.google.com/group/s3ql}{S3QL Mailing List}. You +can subscribe by sending a mail to +\href{mailto:s3ql+subscribe@googlegroups.com}{s3ql+subscribe@googlegroups.com}. + +\end{itemize} + +Please report any bugs you may encounter in the \href{http://code.google.com/p/s3ql/issues/list}{Issue Tracker}. + + + +\renewcommand{\indexname}{Index} +\printindex +\end{document} diff --git a/doc/latex/manual.toc b/doc/latex/manual.toc new file mode 100644 index 0000000..2996158 --- /dev/null +++ b/doc/latex/manual.toc @@ -0,0 +1,142 @@ +\select@language {english} +\contentsline {chapter}{\numberline {1}About S3QL}{1}{chapter.1} +\contentsline {section}{\numberline {1.1}Features}{1}{section.1.1} +\contentsline {section}{\numberline {1.2}Development Status}{2}{section.1.2} +\contentsline {chapter}{\numberline {2}Installation}{3}{chapter.2} +\contentsline {section}{\numberline {2.1}Dependencies}{3}{section.2.1} +\contentsline {section}{\numberline {2.2}Installing S3QL}{4}{section.2.2} +\contentsline {chapter}{\numberline {3}Storage Backends}{5}{chapter.3} +\contentsline {section}{\numberline {3.1}On Backend Reliability}{5}{section.3.1} +\contentsline {section}{\numberline {3.2}The \texttt {authinfo} file}{6}{section.3.2} +\contentsline {section}{\numberline {3.3}Consistency Guarantees}{6}{section.3.3} +\contentsline {subsection}{\numberline {3.3.1}Dealing with Eventual Consistency}{6}{subsection.3.3.1} +\contentsline {section}{\numberline {3.4}The Amazon S3 Backend}{7}{section.3.4} +\contentsline {section}{\numberline {3.5}The Local Backend}{8}{section.3.5} +\contentsline {section}{\numberline {3.6}The SFTP Backend}{8}{section.3.6} +\contentsline {chapter}{\numberline {4}File System Creation}{9}{chapter.4} +\contentsline {chapter}{\numberline {5}Managing Buckets}{11}{chapter.5} +\contentsline {section}{\numberline {5.1}Changing the Passphrase}{11}{section.5.1} +\contentsline {section}{\numberline {5.2}Upgrading the file system}{11}{section.5.2} +\contentsline {section}{\numberline {5.3}Deleting a file system}{12}{section.5.3} +\contentsline {section}{\numberline {5.4}Restoring Metadata Backups}{12}{section.5.4} +\contentsline {chapter}{\numberline {6}Mounting}{13}{chapter.6} +\contentsline {section}{\numberline {6.1}Storing Encryption Passwords}{14}{section.6.1} +\contentsline {section}{\numberline {6.2}Compression Algorithms}{14}{section.6.2} +\contentsline {section}{\numberline {6.3}Parallel Compression}{15}{section.6.3} +\contentsline {section}{\numberline {6.4}Notes about Caching}{15}{section.6.4} +\contentsline {subsection}{\numberline {6.4.1}Maximum Number of Cache Entries}{15}{subsection.6.4.1} +\contentsline {subsection}{\numberline {6.4.2}Cache Flushing and Expiration}{15}{subsection.6.4.2} +\contentsline {section}{\numberline {6.5}Automatic Mounting}{15}{section.6.5} +\contentsline {chapter}{\numberline {7}Advanced S3QL Features}{17}{chapter.7} +\contentsline {section}{\numberline {7.1}Snapshotting and Copy-on-Write}{17}{section.7.1} +\contentsline {subsection}{\numberline {7.1.1}Snapshotting vs Hardlinking}{17}{subsection.7.1.1} +\contentsline {section}{\numberline {7.2}Getting Statistics}{18}{section.7.2} +\contentsline {section}{\numberline {7.3}Immutable Trees}{18}{section.7.3} +\contentsline {section}{\numberline {7.4}Fast Recursive Removal}{19}{section.7.4} +\contentsline {section}{\numberline {7.5}Runtime Configuration}{19}{section.7.5} +\contentsline {chapter}{\numberline {8}Unmounting}{21}{chapter.8} +\contentsline {chapter}{\numberline {9}Checking for Errors}{23}{chapter.9} +\contentsline {chapter}{\numberline {10}Contributed Programs}{25}{chapter.10} +\contentsline {section}{\numberline {10.1}benchmark.py}{25}{section.10.1} +\contentsline {section}{\numberline {10.2}s3\_copy.py}{25}{section.10.2} +\contentsline {section}{\numberline {10.3}pcp.py}{25}{section.10.3} +\contentsline {section}{\numberline {10.4}s3\_backup.sh}{25}{section.10.4} +\contentsline {section}{\numberline {10.5}expire\_backups.py}{26}{section.10.5} +\contentsline {section}{\numberline {10.6}s3ql.conf}{27}{section.10.6} +\contentsline {chapter}{\numberline {11}Tips \& Tricks}{29}{chapter.11} +\contentsline {section}{\numberline {11.1}Permanently mounted backup file system}{29}{section.11.1} +\contentsline {section}{\numberline {11.2}Improving copy performance}{29}{section.11.2} +\contentsline {chapter}{\numberline {12}Known Issues}{31}{chapter.12} +\contentsline {chapter}{\numberline {13}Manpages}{33}{chapter.13} +\contentsline {section}{\numberline {13.1}The \textbf {mkfs.s3ql} command}{33}{section.13.1} +\contentsline {subsection}{\numberline {13.1.1}Synopsis}{33}{subsection.13.1.1} +\contentsline {subsection}{\numberline {13.1.2}Description}{33}{subsection.13.1.2} +\contentsline {subsubsection}{Amazon S3}{33}{subsubsection*.3} +\contentsline {subsubsection}{Local}{33}{subsubsection*.4} +\contentsline {subsubsection}{SFTP}{33}{subsubsection*.5} +\contentsline {subsection}{\numberline {13.1.3}Options}{34}{subsection.13.1.3} +\contentsline {subsection}{\numberline {13.1.4}Files}{34}{subsection.13.1.4} +\contentsline {subsection}{\numberline {13.1.5}Exit Status}{34}{subsection.13.1.5} +\contentsline {subsection}{\numberline {13.1.6}See Also}{34}{subsection.13.1.6} +\contentsline {section}{\numberline {13.2}The \textbf {s3qladm} command}{34}{section.13.2} +\contentsline {subsection}{\numberline {13.2.1}Synopsis}{34}{subsection.13.2.1} +\contentsline {subsection}{\numberline {13.2.2}Description}{35}{subsection.13.2.2} +\contentsline {subsubsection}{Amazon S3}{35}{subsubsection*.6} +\contentsline {subsubsection}{Local}{35}{subsubsection*.7} +\contentsline {subsubsection}{SFTP}{35}{subsubsection*.8} +\contentsline {subsection}{\numberline {13.2.3}Options}{35}{subsection.13.2.3} +\contentsline {subsection}{\numberline {13.2.4}Actions}{35}{subsection.13.2.4} +\contentsline {subsection}{\numberline {13.2.5}Files}{36}{subsection.13.2.5} +\contentsline {subsection}{\numberline {13.2.6}Exit Status}{36}{subsection.13.2.6} +\contentsline {subsection}{\numberline {13.2.7}See Also}{36}{subsection.13.2.7} +\contentsline {section}{\numberline {13.3}The \textbf {mount.s3ql} command}{36}{section.13.3} +\contentsline {subsection}{\numberline {13.3.1}Synopsis}{36}{subsection.13.3.1} +\contentsline {subsection}{\numberline {13.3.2}Description}{36}{subsection.13.3.2} +\contentsline {subsubsection}{Amazon S3}{36}{subsubsection*.9} +\contentsline {subsubsection}{Local}{36}{subsubsection*.10} +\contentsline {subsubsection}{SFTP}{36}{subsubsection*.11} +\contentsline {subsection}{\numberline {13.3.3}Options}{37}{subsection.13.3.3} +\contentsline {subsection}{\numberline {13.3.4}Files}{38}{subsection.13.3.4} +\contentsline {subsection}{\numberline {13.3.5}Exit Status}{38}{subsection.13.3.5} +\contentsline {subsection}{\numberline {13.3.6}See Also}{38}{subsection.13.3.6} +\contentsline {section}{\numberline {13.4}The \textbf {s3qlstat} command}{38}{section.13.4} +\contentsline {subsection}{\numberline {13.4.1}Synopsis}{38}{subsection.13.4.1} +\contentsline {subsection}{\numberline {13.4.2}Description}{38}{subsection.13.4.2} +\contentsline {subsection}{\numberline {13.4.3}Options}{38}{subsection.13.4.3} +\contentsline {subsection}{\numberline {13.4.4}Exit Status}{38}{subsection.13.4.4} +\contentsline {subsection}{\numberline {13.4.5}See Also}{38}{subsection.13.4.5} +\contentsline {section}{\numberline {13.5}The \textbf {s3qlctrl} command}{39}{section.13.5} +\contentsline {subsection}{\numberline {13.5.1}Synopsis}{39}{subsection.13.5.1} +\contentsline {subsection}{\numberline {13.5.2}Description}{39}{subsection.13.5.2} +\contentsline {subsection}{\numberline {13.5.3}Options}{39}{subsection.13.5.3} +\contentsline {subsection}{\numberline {13.5.4}Exit Status}{39}{subsection.13.5.4} +\contentsline {subsection}{\numberline {13.5.5}See Also}{39}{subsection.13.5.5} +\contentsline {section}{\numberline {13.6}The \textbf {s3qlcp} command}{40}{section.13.6} +\contentsline {subsection}{\numberline {13.6.1}Synopsis}{40}{subsection.13.6.1} +\contentsline {subsection}{\numberline {13.6.2}Description}{40}{subsection.13.6.2} +\contentsline {subsubsection}{Snapshotting vs Hardlinking}{40}{subsubsection*.12} +\contentsline {subsection}{\numberline {13.6.3}Options}{40}{subsection.13.6.3} +\contentsline {subsection}{\numberline {13.6.4}Exit Status}{41}{subsection.13.6.4} +\contentsline {subsection}{\numberline {13.6.5}See Also}{41}{subsection.13.6.5} +\contentsline {section}{\numberline {13.7}The \textbf {s3qlrm} command}{41}{section.13.7} +\contentsline {subsection}{\numberline {13.7.1}Synopsis}{41}{subsection.13.7.1} +\contentsline {subsection}{\numberline {13.7.2}Description}{41}{subsection.13.7.2} +\contentsline {subsection}{\numberline {13.7.3}Options}{41}{subsection.13.7.3} +\contentsline {subsection}{\numberline {13.7.4}Exit Status}{41}{subsection.13.7.4} +\contentsline {subsection}{\numberline {13.7.5}See Also}{41}{subsection.13.7.5} +\contentsline {section}{\numberline {13.8}The \textbf {s3qllock} command}{42}{section.13.8} +\contentsline {subsection}{\numberline {13.8.1}Synopsis}{42}{subsection.13.8.1} +\contentsline {subsection}{\numberline {13.8.2}Description}{42}{subsection.13.8.2} +\contentsline {subsection}{\numberline {13.8.3}Rationale}{42}{subsection.13.8.3} +\contentsline {subsection}{\numberline {13.8.4}Options}{42}{subsection.13.8.4} +\contentsline {subsection}{\numberline {13.8.5}Exit Status}{42}{subsection.13.8.5} +\contentsline {subsection}{\numberline {13.8.6}See Also}{43}{subsection.13.8.6} +\contentsline {section}{\numberline {13.9}The \textbf {umount.s3ql} command}{43}{section.13.9} +\contentsline {subsection}{\numberline {13.9.1}Synopsis}{43}{subsection.13.9.1} +\contentsline {subsection}{\numberline {13.9.2}Description}{43}{subsection.13.9.2} +\contentsline {subsection}{\numberline {13.9.3}Options}{43}{subsection.13.9.3} +\contentsline {subsection}{\numberline {13.9.4}Exit Status}{43}{subsection.13.9.4} +\contentsline {subsection}{\numberline {13.9.5}See Also}{43}{subsection.13.9.5} +\contentsline {section}{\numberline {13.10}The \textbf {fsck.s3ql} command}{44}{section.13.10} +\contentsline {subsection}{\numberline {13.10.1}Synopsis}{44}{subsection.13.10.1} +\contentsline {subsection}{\numberline {13.10.2}Description}{44}{subsection.13.10.2} +\contentsline {subsubsection}{Amazon S3}{44}{subsubsection*.13} +\contentsline {subsubsection}{Local}{44}{subsubsection*.14} +\contentsline {subsubsection}{SFTP}{44}{subsubsection*.15} +\contentsline {subsection}{\numberline {13.10.3}Options}{44}{subsection.13.10.3} +\contentsline {subsection}{\numberline {13.10.4}Files}{45}{subsection.13.10.4} +\contentsline {subsection}{\numberline {13.10.5}Exit Status}{45}{subsection.13.10.5} +\contentsline {subsection}{\numberline {13.10.6}See Also}{45}{subsection.13.10.6} +\contentsline {section}{\numberline {13.11}The \textbf {pcp} command}{45}{section.13.11} +\contentsline {subsection}{\numberline {13.11.1}Synopsis}{45}{subsection.13.11.1} +\contentsline {subsection}{\numberline {13.11.2}Description}{45}{subsection.13.11.2} +\contentsline {subsection}{\numberline {13.11.3}Options}{45}{subsection.13.11.3} +\contentsline {subsection}{\numberline {13.11.4}Exit Status}{45}{subsection.13.11.4} +\contentsline {subsection}{\numberline {13.11.5}See Also}{45}{subsection.13.11.5} +\contentsline {section}{\numberline {13.12}The \textbf {expire\_backups} command}{46}{section.13.12} +\contentsline {subsection}{\numberline {13.12.1}Synopsis}{46}{subsection.13.12.1} +\contentsline {subsection}{\numberline {13.12.2}Description}{46}{subsection.13.12.2} +\contentsline {subsection}{\numberline {13.12.3}Options}{47}{subsection.13.12.3} +\contentsline {subsection}{\numberline {13.12.4}Exit Status}{47}{subsection.13.12.4} +\contentsline {subsection}{\numberline {13.12.5}See Also}{47}{subsection.13.12.5} +\contentsline {chapter}{\numberline {14}Further Resources / Getting Help}{49}{chapter.14} diff --git a/doc/latex/python.ist b/doc/latex/python.ist new file mode 100644 index 0000000..9ffa0f9 --- /dev/null +++ b/doc/latex/python.ist @@ -0,0 +1,11 @@ +line_max 100 +headings_flag 1 +heading_prefix " \\bigletter " + +preamble "\\begin{theindex} +\\def\\bigletter#1{{\\Large\\sffamily#1}\\nopagebreak\\vspace{1mm}} + +" + +symhead_positive "{Symbols}" +numhead_positive "{Numbers}" diff --git a/doc/latex/sphinx.sty b/doc/latex/sphinx.sty new file mode 100644 index 0000000..21a3d89 --- /dev/null +++ b/doc/latex/sphinx.sty @@ -0,0 +1,464 @@ +% +% sphinx.sty +% +% Adapted from the old python.sty, mostly written by Fred Drake, +% by Georg Brandl. +% + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesPackage{sphinx}[2010/01/15 LaTeX package (Sphinx markup)] + +\RequirePackage{textcomp} +\RequirePackage{fancyhdr} +\RequirePackage{fancybox} +\RequirePackage{titlesec} +\RequirePackage{tabulary} +\RequirePackage{amsmath} % for \text +\RequirePackage{makeidx} +\RequirePackage{framed} +\RequirePackage{ifthen} +\RequirePackage{color} +% For highlighted code. +\RequirePackage{fancyvrb} +% For table captions. +\RequirePackage{threeparttable} +% Handle footnotes in tables. +\RequirePackage{footnote} +\makesavenoteenv{tabulary} +% For floating figures in the text. +\RequirePackage{wrapfig} +% Separate paragraphs by space by default. +\RequirePackage{parskip} + +% Redefine these colors to your liking in the preamble. +\definecolor{TitleColor}{rgb}{0.126,0.263,0.361} +\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486} +\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388} +% Redefine these colors to something not white if you want to have colored +% background and border for code examples. +\definecolor{VerbatimColor}{rgb}{1,1,1} +\definecolor{VerbatimBorderColor}{rgb}{1,1,1} + +% Uncomment these two lines to ignore the paper size and make the page +% size more like a typical published manual. +%\renewcommand{\paperheight}{9in} +%\renewcommand{\paperwidth}{8.5in} % typical squarish manual +%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python'' + +% For graphicx, check if we are compiling under latex or pdflatex. +\ifx\pdftexversion\undefined + \usepackage{graphicx} +\else + \usepackage[pdftex]{graphicx} +\fi + +% for PDF output, use colors and maximal compression +\newif\ifsphinxpdfoutput\sphinxpdfoutputfalse +\ifx\pdfoutput\undefined\else\ifcase\pdfoutput + \let\py@NormalColor\relax + \let\py@TitleColor\relax +\else + \sphinxpdfoutputtrue + \input{pdfcolor} + \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} + \def\py@TitleColor{\color{TitleColor}} + \pdfcompresslevel=9 +\fi\fi + +% XeLaTeX can do colors, too +\ifx\XeTeXrevision\undefined\else + \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} + \def\py@TitleColor{\color{TitleColor}} +\fi + +% Increase printable page size (copied from fullpage.sty) +\topmargin 0pt +\advance \topmargin by -\headheight +\advance \topmargin by -\headsep + +% attempt to work a little better for A4 users +\textheight \paperheight +\advance\textheight by -2in + +\oddsidemargin 0pt +\evensidemargin 0pt +%\evensidemargin -.25in % for ``manual size'' documents +\marginparwidth 0.5in + +\textwidth \paperwidth +\advance\textwidth by -2in + + +% Style parameters and macros used by most documents here +\raggedbottom +\sloppy +\hbadness = 5000 % don't print trivial gripes + +\pagestyle{empty} % start this way; change for +\pagenumbering{roman} % ToC & chapters + +% Use this to set the font family for headers and other decor: +\newcommand{\py@HeaderFamily}{\sffamily\bfseries} + +% Redefine the 'normal' header/footer style when using "fancyhdr" package: +\@ifundefined{fancyhf}{}{ + % Use \pagestyle{normal} as the primary pagestyle for text. + \fancypagestyle{normal}{ + \fancyhf{} + \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} + \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}} + \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}} + \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}} + \renewcommand{\headrulewidth}{0.4pt} + \renewcommand{\footrulewidth}{0.4pt} + } + % Update the plain style so we get the page number & footer line, + % but not a chapter or section title. This is to keep the first + % page of a chapter and the blank page between chapters `clean.' + \fancypagestyle{plain}{ + \fancyhf{} + \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0.4pt} + } +} + +% Some custom font markup commands. +% +\newcommand{\strong}[1]{{\bf #1}} +\newcommand{\code}[1]{\texttt{#1}} +\newcommand{\bfcode}[1]{\code{\bfseries#1}} +\newcommand{\samp}[1]{`\code{#1}'} +\newcommand{\email}[1]{\textsf{#1}} + +% Redefine the Verbatim environment to allow border and background colors. +% The original environment is still used for verbatims within tables. +\let\OriginalVerbatim=\Verbatim +\let\endOriginalVerbatim=\endVerbatim + +% Play with vspace to be able to keep the indentation. +\newlength\distancetoright +\def\mycolorbox#1{% + \setlength\distancetoright{\linewidth}% + \advance\distancetoright -\@totalleftmargin % + \fcolorbox{VerbatimBorderColor}{VerbatimColor}{% + \begin{minipage}{\distancetoright}% + #1 + \end{minipage}% + }% +} +\def\FrameCommand{\mycolorbox} + +\renewcommand{\Verbatim}[1][1]{% + % list starts new par, but we don't want it to be set apart vertically + \bgroup\parskip=0pt% + \smallskip% + % The list environement is needed to control perfectly the vertical + % space. + \list{}{% + \setlength\parskip{0pt}% + \setlength\itemsep{0ex}% + \setlength\topsep{0ex}% + \setlength\partopsep{0pt}% + \setlength\leftmargin{0pt}% + }% + \item\MakeFramed {\FrameRestore}% + \small% + \OriginalVerbatim[#1]% +} +\renewcommand{\endVerbatim}{% + \endOriginalVerbatim% + \endMakeFramed% + \endlist% + % close group to restore \parskip + \egroup% +} + + +% \moduleauthor{name}{email} +\newcommand{\moduleauthor}[2]{} + +% \sectionauthor{name}{email} +\newcommand{\sectionauthor}[2]{} + +% Augment the sectioning commands used to get our own font family in place, +% and reset some internal data items: +\titleformat{\section}{\Large\py@HeaderFamily}% + {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\subsection}{\large\py@HeaderFamily}% + {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\subsubsection}{\py@HeaderFamily}% + {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\paragraph}{\small\py@HeaderFamily}% + {\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor} + +% {fulllineitems} is the main environment for object descriptions. +% +\newcommand{\py@itemnewline}[1]{% + \@tempdima\linewidth% + \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}% +} + +\newenvironment{fulllineitems}{ + \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt + \rightmargin 0pt \topsep -\parskip \partopsep \parskip + \itemsep -\parsep + \let\makelabel=\py@itemnewline} +}{\end{list}} + +% \optional is used for ``[, arg]``, i.e. desc_optional nodes. +\newcommand{\optional}[1]{% + {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}} + +\newlength{\py@argswidth} +\newcommand{\py@sigparams}[2]{% + \parbox[t]{\py@argswidth}{#1\code{)}#2}} +\newcommand{\pysigline}[1]{\item[#1]\nopagebreak} +\newcommand{\pysiglinewithargsret}[3]{% + \settowidth{\py@argswidth}{#1\code{(}}% + \addtolength{\py@argswidth}{-2\py@argswidth}% + \addtolength{\py@argswidth}{\linewidth}% + \item[#1\code{(}\py@sigparams{#2}{#3}]} + +% Production lists +% +\newenvironment{productionlist}{ +% \def\optional##1{{\Large[}##1{\Large]}} + \def\production##1##2{\\\code{##1}&::=&\code{##2}} + \def\productioncont##1{\\& &\code{##1}} + \parindent=2em + \indent + \begin{tabular}{lcl} +}{% + \end{tabular} +} + +% Notices / Admonitions +% +\newlength{\py@noticelength} + +\newcommand{\py@heavybox}{ + \setlength{\fboxrule}{1pt} + \setlength{\fboxsep}{6pt} + \setlength{\py@noticelength}{\linewidth} + \addtolength{\py@noticelength}{-2\fboxsep} + \addtolength{\py@noticelength}{-2\fboxrule} + %\setlength{\shadowsize}{3pt} + \Sbox + \minipage{\py@noticelength} +} +\newcommand{\py@endheavybox}{ + \endminipage + \endSbox + \fbox{\TheSbox} +} + +\newcommand{\py@lightbox}{{% + \setlength\parskip{0pt}\par + \rule[0ex]{\linewidth}{0.5pt}% + \par\vspace{-0.5ex}% + }} +\newcommand{\py@endlightbox}{{% + \setlength{\parskip}{0pt}% + \par\rule[0.5ex]{\linewidth}{0.5pt}% + \par\vspace{-0.5ex}% + }} + +% Some are quite plain: +\newcommand{\py@noticestart@note}{\py@lightbox} +\newcommand{\py@noticeend@note}{\py@endlightbox} +\newcommand{\py@noticestart@hint}{\py@lightbox} +\newcommand{\py@noticeend@hint}{\py@endlightbox} +\newcommand{\py@noticestart@important}{\py@lightbox} +\newcommand{\py@noticeend@important}{\py@endlightbox} +\newcommand{\py@noticestart@tip}{\py@lightbox} +\newcommand{\py@noticeend@tip}{\py@endlightbox} + +% Others gets more visible distinction: +\newcommand{\py@noticestart@warning}{\py@heavybox} +\newcommand{\py@noticeend@warning}{\py@endheavybox} +\newcommand{\py@noticestart@caution}{\py@heavybox} +\newcommand{\py@noticeend@caution}{\py@endheavybox} +\newcommand{\py@noticestart@attention}{\py@heavybox} +\newcommand{\py@noticeend@attention}{\py@endheavybox} +\newcommand{\py@noticestart@danger}{\py@heavybox} +\newcommand{\py@noticeend@danger}{\py@endheavybox} +\newcommand{\py@noticestart@error}{\py@heavybox} +\newcommand{\py@noticeend@error}{\py@endheavybox} + +\newenvironment{notice}[2]{ + \def\py@noticetype{#1} + \csname py@noticestart@#1\endcsname + \strong{#2} +}{\csname py@noticeend@\py@noticetype\endcsname} + +% Allow the release number to be specified independently of the +% \date{}. This allows the date to reflect the document's date and +% release to specify the release that is documented. +% +\newcommand{\py@release}{} +\newcommand{\version}{} +\newcommand{\shortversion}{} +\newcommand{\releaseinfo}{} +\newcommand{\releasename}{Release} +\newcommand{\release}[1]{% + \renewcommand{\py@release}{\releasename\space\version}% + \renewcommand{\version}{#1}} +\newcommand{\setshortversion}[1]{% + \renewcommand{\shortversion}{#1}} +\newcommand{\setreleaseinfo}[1]{% + \renewcommand{\releaseinfo}{#1}} + +% Allow specification of the author's address separately from the +% author's name. This can be used to format them differently, which +% is a good thing. +% +\newcommand{\py@authoraddress}{} +\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}} + +% This sets up the fancy chapter headings that make the documents look +% at least a little better than the usual LaTeX output. +% +\@ifundefined{ChTitleVar}{}{ + \ChNameVar{\raggedleft\normalsize\py@HeaderFamily} + \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily} + \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily} + % This creates chapter heads without the leading \vspace*{}: + \def\@makechapterhead#1{% + {\parindent \z@ \raggedright \normalfont + \ifnum \c@secnumdepth >\m@ne + \DOCH + \fi + \interlinepenalty\@M + \DOTI{#1} + } + } +} + +% Redefine description environment so that it is usable inside fulllineitems. +% +\renewcommand{\description}{% + \list{}{\labelwidth\z@% + \itemindent-\leftmargin% + \labelsep5pt% + \let\makelabel=\descriptionlabel}} + +% Definition lists; requested by AMK for HOWTO documents. Probably useful +% elsewhere as well, so keep in in the general style support. +% +\newenvironment{definitions}{% + \begin{description}% + \def\term##1{\item[##1]\mbox{}\\*[0mm]} +}{% + \end{description}% +} + +% Tell TeX about pathological hyphenation cases: +\hyphenation{Base-HTTP-Re-quest-Hand-ler} + + +% The following is stuff copied from docutils' latex writer. +% +\newcommand{\optionlistlabel}[1]{\bf #1 \hfill} +\newenvironment{optionlist}[1] +{\begin{list}{} + {\setlength{\labelwidth}{#1} + \setlength{\rightmargin}{1cm} + \setlength{\leftmargin}{\rightmargin} + \addtolength{\leftmargin}{\labelwidth} + \addtolength{\leftmargin}{\labelsep} + \renewcommand{\makelabel}{\optionlistlabel}} +}{\end{list}} + +\newlength{\lineblockindentation} +\setlength{\lineblockindentation}{2.5em} +\newenvironment{lineblock}[1] +{\begin{list}{} + {\setlength{\partopsep}{\parskip} + \addtolength{\partopsep}{\baselineskip} + \topsep0pt\itemsep0.15\baselineskip\parsep0pt + \leftmargin#1} + \raggedright} +{\end{list}} + +% Redefine includgraphics for avoiding images larger than the screen size +% If the size is not specified. +\let\py@Oldincludegraphics\includegraphics + +\newbox\image@box% +\newdimen\image@width% +\renewcommand\includegraphics[2][\@empty]{% + \ifx#1\@empty% + \setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}% + \image@width\wd\image@box% + \ifdim \image@width>\linewidth% + \setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}% + \box\image@box% + \else% + \py@Oldincludegraphics{#2}% + \fi% + \else% + \py@Oldincludegraphics[#1]{#2}% + \fi% +} + + +% Fix the index and bibliography environments to add an entry to the Table of +% Contents; this is much nicer than just having to jump to the end of the book +% and flip around, especially with multiple indexes. +% +\let\py@OldTheindex=\theindex +\renewcommand{\theindex}{ + \cleardoublepage + \phantomsection + \py@OldTheindex + \addcontentsline{toc}{chapter}{\indexname} +} + +\let\py@OldThebibliography=\thebibliography +\renewcommand{\thebibliography}[1]{ + \cleardoublepage + \phantomsection + \py@OldThebibliography{1} + \addcontentsline{toc}{chapter}{\bibname} +} + +% Include hyperref last. +\RequirePackage[colorlinks,breaklinks, + linkcolor=InnerLinkColor,filecolor=OuterLinkColor, + menucolor=OuterLinkColor,urlcolor=OuterLinkColor, + citecolor=InnerLinkColor]{hyperref} +% Fix anchor placement for figures with captions. +% (Note: we don't use a package option here; instead, we give an explicit +% \capstart for figures that actually have a caption.) +\RequirePackage{hypcap} + +% From docutils.writers.latex2e +\providecommand{\DUspan}[2]{% + {% group ("span") to limit the scope of styling commands + \@for\node@class@name:=#1\do{% + \ifcsname docutilsrole\node@class@name\endcsname% + \csname docutilsrole\node@class@name\endcsname% + \fi% + }% + {#2}% node content + }% close "span" +} + +\providecommand*{\DUprovidelength}[2]{ + \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{} +} + +\DUprovidelength{\DUlineblockindent}{2.5em} +\ifthenelse{\isundefined{\DUlineblock}}{ + \newenvironment{DUlineblock}[1]{% + \list{}{\setlength{\partopsep}{\parskip} + \addtolength{\partopsep}{\baselineskip} + \setlength{\topsep}{0pt} + \setlength{\itemsep}{0.15\baselineskip} + \setlength{\parsep}{0pt} + \setlength{\leftmargin}{#1}} + \raggedright + } + {\endlist} +}{} diff --git a/doc/latex/sphinxhowto.cls b/doc/latex/sphinxhowto.cls new file mode 100644 index 0000000..1ebdd43 --- /dev/null +++ b/doc/latex/sphinxhowto.cls @@ -0,0 +1,81 @@ +% +% sphinxhowto.cls for Sphinx (http://sphinx.pocoo.org/) +% + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesClass{sphinxhowto}[2009/06/02 Document class (Sphinx HOWTO)] + +% 'oneside' option overriding the 'twoside' default +\newif\if@oneside +\DeclareOption{oneside}{\@onesidetrue} +% Pass remaining document options to the parent class. +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{\sphinxdocclass}} +\ProcessOptions\relax + +% Default to two-side document +\if@oneside +% nothing to do (oneside is the default) +\else +\PassOptionsToClass{twoside}{\sphinxdocclass} +\fi + +\LoadClass{\sphinxdocclass} + +% Set some sane defaults for section numbering depth and TOC depth. You can +% reset these counters in your preamble. +% +\setcounter{secnumdepth}{2} + +% Change the title page to look a bit better, and fit in with the fncychap +% ``Bjarne'' style a bit better. +% +\renewcommand{\maketitle}{ + \rule{\textwidth}{1pt} + \ifsphinxpdfoutput + \begingroup + % These \defs are required to deal with multi-line authors; it + % changes \\ to ', ' (comma-space), making it pass muster for + % generating document info in the PDF file. + \def\\{, } + \def\and{and } + \pdfinfo{ + /Author (\@author) + /Title (\@title) + } + \endgroup + \fi + \begin{flushright} + \sphinxlogo% + {\rm\Huge\py@HeaderFamily \@title} \par + {\em\large\py@HeaderFamily \py@release\releaseinfo} \par + \vspace{25pt} + {\Large\py@HeaderFamily + \begin{tabular}[t]{c} + \@author + \end{tabular}} \par + \vspace{25pt} + \@date \par + \py@authoraddress \par + \end{flushright} + \@thanks + \setcounter{footnote}{0} + \let\thanks\relax\let\maketitle\relax + %\gdef\@thanks{}\gdef\@author{}\gdef\@title{} +} + +\let\py@OldTableofcontents=\tableofcontents +\renewcommand{\tableofcontents}{ + \begingroup + \parskip = 0mm + \py@OldTableofcontents + \endgroup + \rule{\textwidth}{1pt} + \vspace{12pt} +} + +\@ifundefined{fancyhf}{ + \pagestyle{plain}}{ + \pagestyle{normal}} % start this way; change for +\pagenumbering{arabic} % ToC & chapters + +\thispagestyle{empty} diff --git a/doc/latex/sphinxmanual.cls b/doc/latex/sphinxmanual.cls new file mode 100644 index 0000000..5751779 --- /dev/null +++ b/doc/latex/sphinxmanual.cls @@ -0,0 +1,122 @@ +% +% sphinxmanual.cls for Sphinx (http://sphinx.pocoo.org/) +% + +\NeedsTeXFormat{LaTeX2e}[1995/12/01] +\ProvidesClass{sphinxmanual}[2009/06/02 Document class (Sphinx manual)] + +% chapters starting at odd pages (overridden by 'openany' document option) +\PassOptionsToClass{openright}{\sphinxdocclass} + +% 'oneside' option overriding the 'twoside' default +\newif\if@oneside +\DeclareOption{oneside}{\@onesidetrue} +% Pass remaining document options to the parent class. +\DeclareOption*{\PassOptionsToClass{\CurrentOption}{\sphinxdocclass}} +\ProcessOptions\relax + +% Defaults two-side document +\if@oneside +% nothing to do (oneside is the default) +\else +\PassOptionsToClass{twoside}{\sphinxdocclass} +\fi + +\LoadClass{\sphinxdocclass} + +% Set some sane defaults for section numbering depth and TOC depth. You can +% reset these counters in your preamble. +% +\setcounter{secnumdepth}{2} +\setcounter{tocdepth}{1} + +% Change the title page to look a bit better, and fit in with the fncychap +% ``Bjarne'' style a bit better. +% +\renewcommand{\maketitle}{% + \begin{titlepage}% + \let\footnotesize\small + \let\footnoterule\relax + \rule{\textwidth}{1pt}% + \ifsphinxpdfoutput + \begingroup + % These \defs are required to deal with multi-line authors; it + % changes \\ to ', ' (comma-space), making it pass muster for + % generating document info in the PDF file. + \def\\{, } + \def\and{and } + \pdfinfo{ + /Author (\@author) + /Title (\@title) + } + \endgroup + \fi + \begin{flushright}% + \sphinxlogo% + {\rm\Huge\py@HeaderFamily \@title \par}% + {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par} + \vfill + {\LARGE\py@HeaderFamily + \begin{tabular}[t]{c} + \@author + \end{tabular} + \par} + \vfill\vfill + {\large + \@date \par + \vfill + \py@authoraddress \par + }% + \end{flushright}%\par + \@thanks + \end{titlepage}% + \cleardoublepage% + \setcounter{footnote}{0}% + \let\thanks\relax\let\maketitle\relax + %\gdef\@thanks{}\gdef\@author{}\gdef\@title{} +} + + +% Catch the end of the {abstract} environment, but here make sure the abstract +% is followed by a blank page if the 'openright' option is used. +% +\let\py@OldEndAbstract=\endabstract +\renewcommand{\endabstract}{ + \if@openright + \ifodd\value{page} + \typeout{Adding blank page after the abstract.} + \vfil\pagebreak + \fi + \fi + \py@OldEndAbstract +} + +% This wraps the \tableofcontents macro with all the magic to get the spacing +% right and have the right number of pages if the 'openright' option has been +% used. This eliminates a fair amount of crud in the individual document files. +% +\let\py@OldTableofcontents=\tableofcontents +\renewcommand{\tableofcontents}{% + \setcounter{page}{1}% + \pagebreak% + \pagestyle{plain}% + {% + \parskip = 0mm% + \py@OldTableofcontents% + \if@openright% + \ifodd\value{page}% + \typeout{Adding blank page after the table of contents.}% + \pagebreak\hspace{0pt}% + \fi% + \fi% + \cleardoublepage% + }% + \pagenumbering{arabic}% + \@ifundefined{fancyhf}{}{\pagestyle{normal}}% +} + +% This is needed to get the width of the section # area wide enough in the +% library reference. Doing it here keeps it the same for all the manuals. +% +\renewcommand*\l@section{\@dottedtocline{1}{1.5em}{2.6em}} +\renewcommand*\l@subsection{\@dottedtocline{2}{4.1em}{3.5em}} diff --git a/doc/latex/tabulary.sty b/doc/latex/tabulary.sty new file mode 100644 index 0000000..ba83c0a --- /dev/null +++ b/doc/latex/tabulary.sty @@ -0,0 +1,452 @@ +%% +%% This is file `tabulary.sty', +%% generated with the docstrip utility. +%% +%% The original source files were: +%% +%% tabulary.dtx (with options: `package') +%% DRAFT VERSION +%% +%% File `tabulary.dtx'. +%% Copyright (C) 1995 1996 2003 David Carlisle +%% This file may be distributed under the terms of the LPPL. +%% See 00readme.txt for details. +%% +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{tabulary} + [2007/10/02 v0.9 tabulary package (DPC)] +\RequirePackage{array} +\catcode`\Z=14 +\DeclareOption{debugshow}{\catcode`\Z=9\relax} +\ProcessOptions +\def\arraybackslash{\let\\=\@arraycr} +\def\@finalstrut#1{% + \unskip\ifhmode\nobreak\fi\vrule\@width\z@\@height\z@\@depth\dp#1} +\newcount\TY@count +\def\tabulary{% + \let\TY@final\tabular + \let\endTY@final\endtabular + \TY@tabular} +\def\TY@tabular#1{% + \edef\TY@{\@currenvir}% + {\ifnum0=`}\fi + \@ovxx\TY@linewidth + \@ovyy\TY@tablewidth + \count@\z@ + \@tempswatrue + \@whilesw\if@tempswa\fi{% + \advance\count@\@ne + \expandafter\ifx\csname TY@F\the\count@\endcsname\relax + \@tempswafalse + \else + \expandafter\let\csname TY@SF\the\count@\expandafter\endcsname + \csname TY@F\the\count@\endcsname + \global\expandafter\let\csname TY@F\the\count@\endcsname\relax + \expandafter\let\csname TY@S\the\count@\expandafter\endcsname + \csname TY@\the\count@\endcsname + \fi}% + \global\TY@count\@ne + \TY@width\xdef{0pt}% + \global\TY@tablewidth\z@ + \global\TY@linewidth#1\relax +Z\message{^^J^^JTable^^J% +Z Target Width: \the\TY@linewidth^^J% +Z \string\tabcolsep: \the\tabcolsep\space +Z \string\arrayrulewidth: \the\arrayrulewidth\space +Z \string\doublerulesep: \the\doublerulesep^^J% +Z \string\tymin: \the\tymin\space +Z \string\tymax: \the\tymax^^J}% + \let\@classz\TY@classz + \let\verb\TX@verb + \toks@{}\TY@get@body} +\let\TY@@mkpream\@mkpream +\def\TY@mkpream{% + \def\@addamp{% + \if@firstamp \@firstampfalse \else + \global\advance\TY@count\@ne + \edef\@preamble{\@preamble &}\fi + \TY@width\xdef{0pt}}% + \def\@acol{% + \TY@subwidth\col@sep + \@addtopreamble{\hskip\col@sep}}% + \let\@arrayrule\TY@arrayrule + \let\@classvi\TY@classvi + \def\@classv{\save@decl + \expandafter\NC@ecs\@nextchar\extracolsep{}\extracolsep\@@@ + \sbox\z@{\d@llarbegin\@nextchar\d@llarend}% + \TY@subwidth{\wd\z@}% + \@addtopreamble{\d@llarbegin\the@toks\the\count@\relax\d@llarend}% + \prepnext@tok}% + \global\let\@mkpream\TY@@mkpream + \TY@@mkpream} +\def\TY@arrayrule{% + \TY@subwidth\arrayrulewidth + \@addtopreamble \vline} +\def\TY@classvi{\ifcase \@lastchclass + \@acol \or + \TY@subwidth\doublerulesep + \@addtopreamble{\hskip \doublerulesep}\or + \@acol \or + \@classvii + \fi} +\def\TY@tab{% + \setbox\z@\hbox\bgroup + \let\[$\let\]$% + \let\equation$\let\endequation$% + \col@sep\tabcolsep + \let\d@llarbegin\begingroup\let\d@llarend\endgroup + \let\@mkpream\TY@mkpream + \def\multicolumn##1##2##3{\multispan##1\relax}% + \CT@start\TY@tabarray} +\def\TY@tabarray{\@ifnextchar[{\TY@array}{\@array[t]}} +\def\TY@array[#1]{\@array[t]} +\def\TY@width#1{% + \expandafter#1\csname TY@\the\TY@count\endcsname} +\def\TY@subwidth#1{% + \TY@width\dimen@ + \advance\dimen@-#1\relax + \TY@width\xdef{\the\dimen@}% + \global\advance\TY@linewidth-#1\relax} +\def\endtabulary{% + \gdef\@halignto{}% + \let\TY@footnote\footnote% + \def\footnote{}% prevent footnotes from doing anything + \expandafter\TY@tab\the\toks@ + \crcr\omit + {\xdef\TY@save@row{}% + \loop + \advance\TY@count\m@ne + \ifnum\TY@count>\z@ + \xdef\TY@save@row{\TY@save@row&\omit}% + \repeat}\TY@save@row + \endarray\global\setbox1=\lastbox\setbox0=\vbox{\unvbox1 + \unskip\global\setbox1=\lastbox}\egroup + \dimen@\TY@linewidth + \divide\dimen@\TY@count + \ifdim\dimen@<\tymin + \TY@warn{tymin too large (\the\tymin), resetting to \the\dimen@}% + \tymin\dimen@ + \fi + \setbox\tw@=\hbox{\unhbox\@ne + \loop +\@tempdima=\lastskip +\ifdim\@tempdima>\z@ +Z \message{ecs=\the\@tempdima^^J}% + \global\advance\TY@linewidth-\@tempdima +\fi + \unskip + \setbox\tw@=\lastbox + \ifhbox\tw@ +Z \message{Col \the\TY@count: Initial=\the\wd\tw@\space}% + \ifdim\wd\tw@>\tymax + \wd\tw@\tymax +Z \message{> max\space}% +Z \else +Z \message{ \@spaces\space}% + \fi + \TY@width\dimen@ +Z \message{\the\dimen@\space}% + \advance\dimen@\wd\tw@ +Z \message{Final=\the\dimen@\space}% + \TY@width\xdef{\the\dimen@}% + \ifdim\dimen@<\tymin +Z \message{< tymin}% + \global\advance\TY@linewidth-\dimen@ + \expandafter\xdef\csname TY@F\the\TY@count\endcsname + {\the\dimen@}% + \else + \expandafter\ifx\csname TY@F\the\TY@count\endcsname\z@ +Z \message{***}% + \global\advance\TY@linewidth-\dimen@ + \expandafter\xdef\csname TY@F\the\TY@count\endcsname + {\the\dimen@}% + \else +Z \message{> tymin}% + \global\advance\TY@tablewidth\dimen@ + \global\expandafter\let\csname TY@F\the\TY@count\endcsname + \maxdimen + \fi\fi + \advance\TY@count\m@ne + \repeat}% + \TY@checkmin + \TY@checkmin + \TY@checkmin + \TY@checkmin + \TY@count\z@ + \let\TY@box\TY@box@v + \let\footnote\TY@footnote % restore footnotes + {\expandafter\TY@final\the\toks@\endTY@final}% + \count@\z@ + \@tempswatrue + \@whilesw\if@tempswa\fi{% + \advance\count@\@ne + \expandafter\ifx\csname TY@SF\the\count@\endcsname\relax + \@tempswafalse + \else + \global\expandafter\let\csname TY@F\the\count@\expandafter\endcsname + \csname TY@SF\the\count@\endcsname + \global\expandafter\let\csname TY@\the\count@\expandafter\endcsname + \csname TY@S\the\count@\endcsname + \fi}% + \TY@linewidth\@ovxx + \TY@tablewidth\@ovyy + \ifnum0=`{\fi}} +\def\TY@checkmin{% + \let\TY@checkmin\relax +\ifdim\TY@tablewidth>\z@ + \Gscale@div\TY@ratio\TY@linewidth\TY@tablewidth + \ifdim\TY@tablewidth <\linewidth + \def\TY@ratio{1}% + \fi +\else + \TY@warn{No suitable columns!}% + \def\TY@ratio{1}% +\fi +\count@\z@ +Z \message{^^JLine Width: \the\TY@linewidth, +Z Natural Width: \the\TY@tablewidth, +Z Ratio: \TY@ratio^^J}% +\@tempdima\z@ +\loop +\ifnum\count@<\TY@count +\advance\count@\@ne + \ifdim\csname TY@F\the\count@\endcsname>\tymin + \dimen@\csname TY@\the\count@\endcsname + \dimen@\TY@ratio\dimen@ + \ifdim\dimen@<\tymin +Z \message{Column \the\count@\space ->}% + \global\expandafter\let\csname TY@F\the\count@\endcsname\tymin + \global\advance\TY@linewidth-\tymin + \global\advance\TY@tablewidth-\csname TY@\the\count@\endcsname + \let\TY@checkmin\TY@@checkmin + \else + \expandafter\xdef\csname TY@F\the\count@\endcsname{\the\dimen@}% + \advance\@tempdima\csname TY@F\the\count@\endcsname + \fi + \fi +Z \dimen@\csname TY@F\the\count@\endcsname\message{\the\dimen@, }% +\repeat +Z \message{^^JTotal:\the\@tempdima^^J}% +} +\let\TY@@checkmin\TY@checkmin +\newdimen\TY@linewidth +\def\tyformat{\everypar{{\nobreak\hskip\z@skip}}} +\newdimen\tymin +\tymin=10pt +\newdimen\tymax +\tymax=2\textwidth +\def\@testpach{\@chclass + \ifnum \@lastchclass=6 \@ne \@chnum \@ne \else + \ifnum \@lastchclass=7 5 \else + \ifnum \@lastchclass=8 \tw@ \else + \ifnum \@lastchclass=9 \thr@@ + \else \z@ + \ifnum \@lastchclass = 10 \else + \edef\@nextchar{\expandafter\string\@nextchar}% + \@chnum + \if \@nextchar c\z@ \else + \if \@nextchar l\@ne \else + \if \@nextchar r\tw@ \else + \if \@nextchar C7 \else + \if \@nextchar L8 \else + \if \@nextchar R9 \else + \if \@nextchar J10 \else + \z@ \@chclass + \if\@nextchar |\@ne \else + \if \@nextchar !6 \else + \if \@nextchar @7 \else + \if \@nextchar <8 \else + \if \@nextchar >9 \else + 10 + \@chnum + \if \@nextchar m\thr@@\else + \if \@nextchar p4 \else + \if \@nextchar b5 \else + \z@ \@chclass \z@ \@preamerr \z@ \fi \fi \fi \fi\fi \fi \fi\fi \fi + \fi \fi \fi \fi \fi \fi \fi \fi \fi \fi \fi} +\def\TY@classz{% + \@classx + \@tempcnta\count@ + \ifx\TY@box\TY@box@v + \global\advance\TY@count\@ne + \fi + \let\centering c% + \let\raggedright\noindent + \let\raggedleft\indent + \let\arraybackslash\relax + \prepnext@tok + \ifnum\@chnum<4 + \global\expandafter\let\csname TY@F\the\TY@count\endcsname\z@ + \fi + \ifnum\@chnum=6 + \global\expandafter\let\csname TY@F\the\TY@count\endcsname\z@ + \fi + \@addtopreamble{% + \ifcase\@chnum + \hfil \d@llarbegin\insert@column\d@llarend \hfil \or + \kern\z@ + \d@llarbegin \insert@column \d@llarend \hfil \or + \hfil\kern\z@ \d@llarbegin \insert@column \d@llarend \or + $\vcenter\@startpbox{\@nextchar}\insert@column \@endpbox $\or + \vtop \@startpbox{\@nextchar}\insert@column \@endpbox \or + \vbox \@startpbox{\@nextchar}\insert@column \@endpbox \or + \d@llarbegin \insert@column \d@llarend \or% dubious "s" case + \TY@box\centering\or + \TY@box\raggedright\or + \TY@box\raggedleft\or + \TY@box\relax + \fi}\prepnext@tok} +\def\TY@box#1{% + \ifx\centering#1% + \hfil \d@llarbegin\insert@column\d@llarend \hfil \else + \ifx\raggedright#1% + \kern\z@%<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< + \d@llarbegin \insert@column \d@llarend \hfil \else + \ifx\raggedleft#1% + \hfil\kern\z@ \d@llarbegin \insert@column \d@llarend \else + \ifx\relax#1% + \d@llarbegin \insert@column \d@llarend + \fi \fi \fi \fi} +\def\TY@box@v#1{% + \vtop \@startpbox{\csname TY@F\the\TY@count\endcsname}% + #1\arraybackslash\tyformat + \insert@column\@endpbox} +\newdimen\TY@tablewidth +\def\Gscale@div#1#2#3{% + \setlength\dimen@{#3}% + \ifdim\dimen@=\z@ + \PackageError{graphics}{Division by 0}\@eha + \dimen@#2% + \fi + \edef\@tempd{\the\dimen@}% + \setlength\dimen@{#2}% + \count@65536\relax + \ifdim\dimen@<\z@ + \dimen@-\dimen@ + \count@-\count@ + \fi + \loop + \ifdim\dimen@<8192\p@ + \dimen@\tw@\dimen@ + \divide\count@\tw@ + \repeat + \dimen@ii=\@tempd\relax + \divide\dimen@ii\count@ + \divide\dimen@\dimen@ii + \edef#1{\strip@pt\dimen@}} +\long\def\TY@get@body#1\end + {\toks@\expandafter{\the\toks@#1}\TY@find@end} +\def\TY@find@end#1{% + \def\@tempa{#1}% + \ifx\@tempa\TY@\def\@tempa{\end{#1}}\expandafter\@tempa + \else\toks@\expandafter + {\the\toks@\end{#1}}\expandafter\TY@get@body\fi} +\def\TY@warn{% + \PackageWarning{tabulary}} +\catcode`\Z=11 +\AtBeginDocument{ +\@ifpackageloaded{colortbl}{% +\expandafter\def\expandafter\@mkpream\expandafter#\expandafter1% + \expandafter{% + \expandafter\let\expandafter\CT@setup\expandafter\relax + \expandafter\let\expandafter\CT@color\expandafter\relax + \expandafter\let\expandafter\CT@do@color\expandafter\relax + \expandafter\let\expandafter\color\expandafter\relax + \expandafter\let\expandafter\CT@column@color\expandafter\relax + \expandafter\let\expandafter\CT@row@color\expandafter\relax + \@mkpream{#1}} +\let\TY@@mkpream\@mkpream +\def\TY@classz{% + \@classx + \@tempcnta\count@ + \ifx\TY@box\TY@box@v + \global\advance\TY@count\@ne + \fi + \let\centering c% + \let\raggedright\noindent + \let\raggedleft\indent + \let\arraybackslash\relax + \prepnext@tok +\expandafter\CT@extract\the\toks\@tempcnta\columncolor!\@nil + \ifnum\@chnum<4 + \global\expandafter\let\csname TY@F\the\TY@count\endcsname\z@ + \fi + \ifnum\@chnum=6 + \global\expandafter\let\csname TY@F\the\TY@count\endcsname\z@ + \fi + \@addtopreamble{% + \setbox\z@\hbox\bgroup\bgroup + \ifcase\@chnum + \hskip\stretch{.5}\kern\z@ + \d@llarbegin\insert@column\d@llarend\hskip\stretch{.5}\or + \kern\z@%<<<<<<<<<<<<<<<<<<<<<<<<<<< + \d@llarbegin \insert@column \d@llarend \hfill \or + \hfill\kern\z@ \d@llarbegin \insert@column \d@llarend \or + $\vcenter\@startpbox{\@nextchar}\insert@column \@endpbox $\or + \vtop \@startpbox{\@nextchar}\insert@column \@endpbox \or + \vbox \@startpbox{\@nextchar}\insert@column \@endpbox \or + \d@llarbegin \insert@column \d@llarend \or% dubious s case + \TY@box\centering\or + \TY@box\raggedright\or + \TY@box\raggedleft\or + \TY@box\relax + \fi + \egroup\egroup +\begingroup + \CT@setup + \CT@column@color + \CT@row@color + \CT@do@color +\endgroup + \@tempdima\ht\z@ + \advance\@tempdima\minrowclearance + \vrule\@height\@tempdima\@width\z@ +\unhbox\z@ +}\prepnext@tok}% + \def\TY@arrayrule{% + \TY@subwidth\arrayrulewidth + \@addtopreamble{{\CT@arc@\vline}}}% + \def\TY@classvi{\ifcase \@lastchclass + \@acol \or + \TY@subwidth\doublerulesep + \ifx\CT@drsc@\relax + \@addtopreamble{\hskip\doublerulesep}% + \else + \@addtopreamble{{\CT@drsc@\vrule\@width\doublerulesep}}% + \fi\or + \@acol \or + \@classvii + \fi}% +}{% +\let\CT@start\relax +} +} +{\uccode`\*=`\ % +\uppercase{\gdef\TX@verb{% + \leavevmode\null\TX@vwarn + {\ifnum0=`}\fi\ttfamily\let\\\ignorespaces + \@ifstar{\let~*\TX@vb}{\TX@vb}}}} +\def\TX@vb#1{\def\@tempa##1#1{\toks@{##1}\edef\@tempa{\the\toks@}% + \expandafter\TX@v\meaning\@tempa\\ \\\ifnum0=`{\fi}}\@tempa!} +\def\TX@v#1!{\afterassignment\TX@vfirst\let\@tempa= } +\begingroup +\catcode`\*=\catcode`\# +\catcode`\#=12 +\gdef\TX@vfirst{% + \if\@tempa#% + \def\@tempb{\TX@v@#}% + \else + \let\@tempb\TX@v@ + \if\@tempa\space~\else\@tempa\fi + \fi + \@tempb} +\gdef\TX@v@*1 *2{% + \TX@v@hash*1##\relax\if*2\\\else~\expandafter\TX@v@\fi*2} +\gdef\TX@v@hash*1##*2{*1\ifx*2\relax\else#\expandafter\TX@v@hash\fi*2} +\endgroup +\def\TX@vwarn{% + \@warning{\noexpand\verb may be unreliable inside tabularx/y}% + \global\let\TX@vwarn\@empty} +\endinput +%% +%% End of file `tabulary.sty'. |