.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "rt-serializer 8"
.TH rt-serializer 8 "2017-01-05" "perl v5.20.2" "Request Tracker Reference"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
rt\-serializer \- Serialize an RT database to disk
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    rt\-validator \-\-check && rt\-serializer
.Ve
.PP
This script is used to write out the entire \s-1RT\s0 database to disk, for
later import into a different \s-1RT\s0 instance.  It requires that the data in
the database be self-consistent, in order to do so; please make sure
that the database being exported passes validation by rt-validator
before attempting to use \f(CW\*(C`rt\-serializer\*(C'\fR.
.PP
While running, it will attempt to estimate the number of remaining
objects to be serialized; these estimates are pessimistic, and will be
incorrect if \f(CW\*(C`\-\-no\-users\*(C'\fR, \f(CW\*(C`\-\-no\-groups\*(C'\fR, or \f(CW\*(C`\-\-no\-tickets\*(C'\fR are used.
.PP
If the controlling terminal is large enough (more than 25 columns high)
and the \f(CW\*(C`gnuplot\*(C'\fR program is installed, it will also show a textual
graph of the queue size over time.
.SS "\s-1OPTIONS\s0"
.IX Subsection "OPTIONS"
.IP "\fB\-\-directory\fR \fIname\fR" 4
.IX Item "--directory name"
The name of the output directory to write data files to, which should
not exist yet; it is a fatal error if it does.  Defaults to
\&\f(CW\*(C`./\f(CI$Organization\f(CW:\f(CIDate\f(CW/\*(C'\fR, where \fI\f(CI$Organization\fI\fR is as set in
\&\fIRT_SiteConfig.pm\fR, and \fIDate\fR is today's date.
.IP "\fB\-\-force\fR" 4
.IX Item "--force"
Remove the output directory before starting.
.IP "\fB\-\-size\fR \fImegabytes\fR" 4
.IX Item "--size megabytes"
By default, \f(CW\*(C`rt\-serializer\*(C'\fR chunks its output into data files which are
around 32Mb in size; this option is used to set a different threshold
size, in megabytes.  Note that this is the threshold after which it
rotates to writing a new file, and is as such the \fIlower bound\fR on the
size of each output file.
.IP "\fB\-\-no\-users\fR" 4
.IX Item "--no-users"
By default, all privileged users are serialized; passing \f(CW\*(C`\-\-no\-users\*(C'\fR
limits it to only those users which are referenced by serialized tickets
and history, and are thus necessary for internal consistency.
.IP "\fB\-\-no\-groups\fR" 4
.IX Item "--no-groups"
By default, all groups are serialized; passing \f(CW\*(C`\-\-no\-groups\*(C'\fR limits it
to only system-internal groups, which are needed for internal
consistency.
.IP "\fB\-\-no\-deleted\fR" 4
.IX Item "--no-deleted"
By default, all tickets, including deleted tickets, are serialized;
passing \f(CW\*(C`\-\-no\-deleted\*(C'\fR skips deleted tickets during serialization.
.IP "\fB\-\-scrips\fR" 4
.IX Item "--scrips"
No scrips or templates are serialized by default; this option forces all
scrips and templates to be serialized.
.IP "\fB\-\-acls\fR" 4
.IX Item "--acls"
No ACLs are serialized by default; this option forces all ACLs to be
serialized.
.IP "\fB\-\-no\-tickets\fR" 4
.IX Item "--no-tickets"
Skip serialization of all ticket data.
.IP "\fB\-\-clone\fR" 4
.IX Item "--clone"
Serializes your entire database, creating a clone.  This option should
be used if you want to migrate your \s-1RT\s0 database from one database type
to another (e.g.  MySQL to Postgres).  It is an error to combine
\&\f(CW\*(C`\-\-clone\*(C'\fR with any option that limits object types serialized.  No
dependency walking is performed when cloning. \f(CW\*(C`rt\-importer\*(C'\fR will detect
that your serialized data set was generated by a clone.
.IP "\fB\-\-incremental\fR" 4
.IX Item "--incremental"
Will generate an incremenal serialized dataset using the data stored in
your IncrementalRecords database table.  This assumes that you have created
that table and run \s-1RT\s0 using the Record_Local.pm shim as documented in
\&\f(CW\*(C`docs/incremental\-export/\*(C'\fR.
.IP "\fB\-\-gc\fR \fIn\fR" 4
.IX Item "--gc n"
Adjust how often the garbage collection sweep is done; lower numbers are
more frequent.  See \*(L"\s-1GARBAGE COLLECTION\*(R"\s0.
.IP "\fB\-\-page\fR \fIn\fR" 4
.IX Item "--page n"
Adjust how many rows are pulled from the database in a single query.  Disable
paging by setting this to 0.  Defaults to 100.
.Sp
Keep in mind that rows from \s-1RT\s0's Attachments table are the limiting factor when
determining page size.  You should likely be aiming for 60\-75% of your total
memory on an otherwise unloaded box.
.IP "\fB\-\-quiet\fR" 4
.IX Item "--quiet"
Do not show graphical progress \s-1UI.\s0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
Do not show graphical progress \s-1UI,\s0 but rather log was each row is
written out.
.SH "GARBAGE COLLECTION"
.IX Header "GARBAGE COLLECTION"
\&\f(CW\*(C`rt\-serializer\*(C'\fR maintains a priority queue of objects to serialize, or
searches which may result in objects to serialize.  When inserting into
this queue, it does no checking if the object in question is already in
the queue, or if the search will contain any results.  These checks are
done when the object reaches the front of the queue, or during periodic
garbage collection.
.PP
During periodic garbage collection, the entire queue is swept for
objects which have already been serialized, occur more than once in the
queue, and searches which contain no results in the database.  This is
done to reduce the memory footprint of the serialization process, and is
triggered when enough new objects have been placed in the queue.  This
parameter is tunable via the \f(CW\*(C`\-\-gc\*(C'\fR parameter, which defaults to
running garbage collection every 5,000 objects inserted into the queue;
smaller numbers will result in more frequent garbage collection.
.PP
The default of 5,000 is roughly tuned based on a database with several
thousand tickets, but optimal values will vary wildly depending on
database configuration and size.  Values as low as 25 have provided
speedups with smaller databases; if speed is a factor, experimenting
with different \f(CW\*(C`\-\-gc\*(C'\fR values may be helpful.  Note that there are
significant boundary condition changes in serialization rate, as the
queue empties and fills, causing the time estimates to be rather
imprecise near the start and end of the process.
.PP
Setting \f(CW\*(C`\-\-gc\*(C'\fR to 0 turns off all garbage collection.  Be aware that
this will bloat the memory usage of the serializer.  Any negative value
for \f(CW\*(C`\-\-gc\*(C'\fR turns off periodic garbage collection and instead objects
already serialized or in the queue are checked for at the time they
would be inserted.