git.sur5r.net Git - bacula/docs/blob - docs/manual-fr/storage.tex

   1 %%
   2 %%
   3
   4 \section*{Storage Daemon Design}
   5 \label{_ChapterStart3}
   6 \index{Storage Daemon Design }
   7 \index{Design!Storage Daemon }
   8 \addcontentsline{toc}{section}{Storage Daemon Design}
   9
  10 This chapter is intended to be a technical discussion of the Storage daemon
  11 services and as such is not targeted at end users but rather at developers and
  12 system administrators that want or need to know more of the working details of
  13 {\bf Bacula}.
  14
  15 \subsection*{SD Design Introduction}
  16 \index{Introduction!SD Design }
  17 \index{SD Design Introduction }
  18 \addcontentsline{toc}{subsection}{SD Design Introduction}
  19
  20 The Bacula Storage daemon provides storage resources to a Bacula installation.
  21 An individual Storage daemon is associated with a physical permanent storage
  22 device (for example, a tape drive, CD writer, tape changer or jukebox, etc.),
  23 and may employ auxiliary storage resources (such as space on a hard disk file
  24 system) to increase performance and/or optimize use of the permanent storage
  25 medium.
  26
  27 Any number of storage daemons may be run on a given machine; each associated
  28 with an individual storage device connected to it, and BACULA operations may
  29 employ storage daemons on any number of hosts connected by a network, local or
  30 remote. The ability to employ remote storage daemons (with appropriate
  31 security measures) permits automatic off-site backup, possibly to publicly
  32 available backup repositories.
  33
  34 \subsection*{SD Development Outline}
  35 \index{Outline!SD Development }
  36 \index{SD Development Outline }
  37 \addcontentsline{toc}{subsection}{SD Development Outline}
  38
  39 In order to provide a high performance backup and restore solution that scales
  40 to very large capacity devices and networks, the storage daemon must be able
  41 to extract as much performance from the storage device and network with which
  42 it interacts. In order to accomplish this, storage daemons will eventually
  43 have to sacrifice simplicity and painless portability in favor of techniques
  44 which improve performance. My goal in designing the storage daemon protocol
  45 and developing the initial prototype storage daemon is to provide for these
  46 additions in the future, while implementing an initial storage daemon which is
  47 very simple and portable to almost any POSIX-like environment. This original
  48 storage daemon (and its evolved descendants) can serve as a portable solution
  49 for non-demanding backup requirements (such as single servers of modest size,
  50 individual machines, or small local networks), while serving as the starting
  51 point for development of higher performance configurable derivatives which use
  52 techniques such as POSIX threads, shared memory, asynchronous I/O, buffering
  53 to high-speed intermediate media, and support for tape changers and jukeboxes.
  54
  55
  56 \subsection*{SD Connections and Sessions}
  57 \index{Sessions!SD Connections and }
  58 \index{SD Connections and Sessions }
  59 \addcontentsline{toc}{subsection}{SD Connections and Sessions}
  60
  61 A client connects to a storage server by initiating a conventional TCP
  62 connection. The storage server accepts the connection unless its maximum
  63 number of connections has been reached or the specified host is not granted
  64 access to the storage server. Once a connection has been opened, the client
  65 may make any number of Query requests, and/or initiate (if permitted), one or
  66 more Append sessions (which transmit data to be stored by the storage daemon)
  67 and/or Read sessions (which retrieve data from the storage daemon).
  68
  69 Most requests and replies sent across the connection are simple ASCII strings,
  70 with status replies prefixed by a four digit status code for easier parsing.
  71 Binary data appear in blocks stored and retrieved from the storage. Any
  72 request may result in a single-line status reply of ``{\tt 3201\ Notification\
  73 pending}'', which indicates the client must send a ``Query notification''
  74 request to retrieve one or more notifications posted to it. Once the
  75 notifications have been returned, the client may then resubmit the request
  76 which resulted in the 3201 status.
  77
  78 The following descriptions omit common error codes, yet to be defined, which
  79 can occur from most or many requests due to events like media errors,
  80 restarting of the storage daemon, etc. These details will be filled in, along
  81 with a comprehensive list of status codes along with which requests can
  82 produce them in an update to this document.
  83
  84 \subsubsection*{SD Append Requests}
  85 \index{Requests!SD Append }
  86 \index{SD Append Requests }
  87 \addcontentsline{toc}{subsubsection}{SD Append Requests}
  88
  89 \begin{description}
  90
  91 \item [{append open session = \lt{}JobId\gt{} [  \lt{}Password\gt{} ]  }]
  92    \index{SPAN class }
  93    A data append session is opened with the Job ID given by  {\it JobId} with
  94 client password (if required) given by {\it Password}.  If the session is
  95 successfully opened, a status of {\tt 3000\ OK} is  returned with a ``{\tt
  96 ticket\ =\ }{\it number}'' reply used to  identify subsequent messages in the
  97 session. If too many sessions are open, or  a conflicting session (for
  98 example, a read in progress when simultaneous read  and append sessions are
  99 not permitted), a status of  ``{\tt 3502\ Volume\ busy}'' is returned. If no
 100 volume is mounted, or  the volume mounted cannot be appended to, a status of
 101 ``{\tt 3503\ Volume\ not\ mounted}'' is returned.
 102
 103 \item [append data = \lt{}ticket-number\gt{}  ]
 104    \index{SPAN class }
 105    If the append data is accepted, a  status of {\tt 3000\ OK data address =
 106 \lt{}IPaddress\gt{} port = \lt{}port\gt{}} is returned,  where the {\tt
 107 IPaddress} and {\tt port} specify the IP address and  port number of the data
 108 channel. Error status codes are  {\tt 3504\ Invalid\ ticket\ number} and  {\tt
 109 3505\ Session\ aborted}, the latter of which indicates the  entire append
 110 session has failed due to a daemon or media error.
 111
 112 Once the File daemon has established the connection to the data channel
 113 opened by the Storage daemon, it will transfer a header packet followed  by
 114 any number of data packets. The header packet is of the form:
 115
 116 {\tt \lt{}file-index\gt{} \lt{}stream-id\gt{} \lt{}info\gt{}}
 117
 118 The details are specified in the
 119 \ilink{Daemon Protocol}{_ChapterStart2}  section of this
 120 document.
 121
 122 \item [*append abort session = \lt{}ticket-number\gt{}  ]
 123    \index{SPAN class }
 124    The open append session with ticket {\it ticket-number} is aborted; any blocks
 125 not yet written to permanent media are discarded. Subsequent attempts to
 126 append data to the session will receive an error status of  {\tt 3505\
 127 Session\ aborted}.
 128
 129 \item [append end session = \lt{}ticket-number\gt{}  ]
 130    \index{SPAN class }
 131    The open append session with ticket {\it ticket-number} is marked complete; no
 132 further blocks may be appended. The storage daemon will give priority to
 133 saving  any buffered blocks from this session to permanent media as soon as
 134 possible.
 135
 136 \item [append close session = \lt{}ticket-number\gt{}  ]
 137    \index{SPAN class }
 138    The append session with ticket {\it ticket} is closed. This message  does not
 139 receive an {\tt 3000\ OK} reply until all of the content of the  session are
 140 stored on permanent media, at which time said reply is given,  followed by a
 141 list of volumes, from first to last, which contain blocks from  the session,
 142 along with the first and last file and block on each containing  session data
 143 and the volume session key identifying data from that session in  lines with
 144 the following format:
 145
 146 {\tt {\tt Volume = }\lt{}Volume-id\gt{} \lt{}start-file\gt{}
 147 \lt{}start-block\gt{}  \lt{}end-file\gt{} \lt{}end-block\gt{}
 148 \lt{}volume-session-id\gt{}}where {\it Volume-id} is the volume label,  {\it
 149 start-file} and {\it start-block} are the file and block containing the  first
 150 data from that session on the volume, {\it end-file} and  {\it end-block} are
 151 the file and block with the last data from the session on  the volume and {\it
 152 volume-session-id} is the volume session ID for blocks from the  session
 153 stored on that volume.
 154 \end{description}
 155
 156 \subsubsection*{SD Read Requests}
 157 \index{SD Read Requests }
 158 \index{Requests!SD Read }
 159 \addcontentsline{toc}{subsubsection}{SD Read Requests}
 160
 161 \begin{description}
 162
 163 \item [Read open session = \lt{}JobId\gt{} \lt{}Volume-id\gt{}
 164    \lt{}start-file\gt{} \lt{}start-block\gt{}  \lt{}end-file\gt{}
 165    \lt{}end-block\gt{} \lt{}volume-session-id\gt{} \lt{}password\gt{}  ]
 166 \index{SPAN class }
 167 where {\it Volume-id} is the volume label,  {\it start-file} and {\it
 168 start-block} are the file and block containing the  first data from that
 169 session on the volume, {\it end-file} and  {\it end-block} are the file and
 170 block with the last data from the session on  the volume and {\it
 171 volume-session-id} is the volume session ID for blocks from the  session
 172 stored on that volume.
 173
 174 If the session is successfully opened, a status of
 175
 176 {\tt {\tt 3100\ OK Ticket\ =\ }{\it number}``}
 177
 178 is returned with a reply used to identify  subsequent messages in the session.
 179 If too many sessions are open, or a  conflicting session (for example, an
 180 append in progress when simultaneous read  and append sessions are not
 181 permitted), a status of  ''{\tt 3502\ Volume\ busy}`` is returned. If no
 182 volume is mounted, or  the volume mounted cannot be appended to, a status of
 183 ''{\tt 3503\ Volume\ not\ mounted}`` is returned. If no block with  the given
 184 volume session ID and the correct client ID number appears in the  given first
 185 file and block for the volume, a status of  ''{\tt 3505\ Session\ not\
 186 found}`` is returned.
 187
 188 \item [Read data = \lt{}Ticket\gt{} \gt{} \lt{}Block\gt{}  ]
 189    \index{SPAN class }
 190    The specified Block of data from open read session with the specified Ticket
 191 number  is returned, with a status of {\tt 3000\ OK} followed  by a ''{\tt
 192 Length\ =\ }{\it size}`` line giving the length in  bytes of the block data
 193 which immediately follows. Blocks must be retrieved in  ascending order, but
 194 blocks may be skipped. If a block number greater than the  largest stored on
 195 the volume is requested, a status of  ''{\tt 3201\ End\ of\ volume}`` is
 196 returned. If a block number  greater than the largest in the file is
 197 requested, a status of  ''{\tt 3401\ End\ of\ file}`` is returned.
 198
 199 \item [Read close session = \lt{}Ticket\gt{}  ]
 200    \index{SPAN class }
 201    The read session with Ticket number is closed. A read session  may be closed
 202 at any time; you needn't read all its blocks before closing it.
 203 \end{description}
 204
 205 {\it by
 206 \elink{John Walker}{http://www.fourmilab.ch/}
 207 January 30th, MM }