4 \section*{Storage Daemon Design}
6 \index{Storage Daemon Design }
7 \index{Design!Storage Daemon }
8 \addcontentsline{toc}{section}{Storage Daemon Design}
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
15 \subsection*{SD Design Introduction}
16 \index{Introduction!SD Design }
17 \index{SD Design Introduction }
18 \addcontentsline{toc}{subsection}{SD Design Introduction}
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
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.
34 \subsection*{SD Development Outline}
35 \index{Outline!SD Development }
36 \index{SD Development Outline }
37 \addcontentsline{toc}{subsection}{SD Development Outline}
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.
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}
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).
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.
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.
84 \subsubsection*{SD Append Requests}
85 \index{Requests!SD Append }
86 \index{SD Append Requests }
87 \addcontentsline{toc}{subsubsection}{SD Append Requests}
91 \item [{append open session = \lt{}JobId\gt{} [ \lt{}Password\gt{} ] }]
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.
103 \item [append data = \lt{}ticket-number\gt{} ]
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.
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:
116 {\tt \lt{}file-index\gt{} \lt{}stream-id\gt{} \lt{}info\gt{}}
118 The details are specified in the
119 \ilink{Daemon Protocol}{_ChapterStart2} section of this
122 \item [*append abort session = \lt{}ticket-number\gt{} ]
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\
129 \item [append end session = \lt{}ticket-number\gt{} ]
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
136 \item [append close session = \lt{}ticket-number\gt{} ]
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:
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.
156 \subsubsection*{SD Read Requests}
157 \index{SD Read Requests }
158 \index{Requests!SD Read }
159 \addcontentsline{toc}{subsubsection}{SD Read Requests}
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{} ]
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.
174 If the session is successfully opened, a status of
176 {\tt {\tt 3100\ OK Ticket\ =\ }{\it number}``}
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.
188 \item [Read data = \lt{}Ticket\gt{} \gt{} \lt{}Block\gt{} ]
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.
199 \item [Read close session = \lt{}Ticket\gt{} ]
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.
206 \elink{John Walker}{http://www.fourmilab.ch/}