1# BEGIN BPS TAGGED BLOCK {{{
2#
3# COPYRIGHT:
4#
5# This software is Copyright (c) 1996-2021 Best Practical Solutions, LLC
6#                                          <sales@bestpractical.com>
7#
8# (Except where explicitly superseded by other copyright notices)
9#
10#
11# LICENSE:
12#
13# This work is made available to you under the terms of Version 2 of
14# the GNU General Public License. A copy of that license should have
15# been provided with this software, but in any event can be snarfed
16# from www.gnu.org.
17#
18# This work is distributed in the hope that it will be useful, but
19# WITHOUT ANY WARRANTY; without even the implied warranty of
20# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21# General Public License for more details.
22#
23# You should have received a copy of the GNU General Public License
24# along with this program; if not, write to the Free Software
25# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
26# 02110-1301 or visit their web page on the internet at
27# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
28#
29#
30# CONTRIBUTION SUBMISSION POLICY:
31#
32# (The following paragraph is not intended to limit the rights granted
33# to you to modify and distribute this software under the terms of
34# the GNU General Public License and is only of importance to you if
35# you choose to contribute your changes and enhancements to the
36# community by submitting them to Best Practical Solutions, LLC.)
37#
38# By intentionally submitting any modifications, corrections or
39# derivatives to this work, or any other work intended for use with
40# Request Tracker, to Best Practical Solutions, LLC, you confirm that
41# you are the copyright holder for those contributions and you grant
42# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
43# royalty-free, perpetual, license to use, copy, create derivative
44# works based on those contributions, and sublicense and distribute
45# those contributions and any derivatives thereof.
46#
47# END BPS TAGGED BLOCK }}}
48
49use warnings;
50use strict;
51
52package RT::ExternalStorage;
53
54require RT::ExternalStorage::Backend;
55
56=head1 NAME
57
58RT::ExternalStorage - Store attachments outside the database
59
60=head1 SYNOPSIS
61
62    Set(%ExternalStorage,
63        Type => 'Disk',
64        Path => '/opt/rt5/var/attachments',
65    );
66
67=head1 DESCRIPTION
68
69By default, RT stores attachments in the database.  ExternalStorage moves
70all attachments that RT does not need efficient access to (which include
71textual content and images) to outside of the database.  This may either
72be on local disk, or to a cloud storage solution.  This decreases the
73size of RT's database, in turn decreasing the burden of backing up RT's
74database, at the cost of adding additional locations which must be
75configured or backed up.  Attachment storage paths are calculated based
76on file contents; this provides de-duplication.
77
78The files are initially stored in the database when RT receives
79them; this guarantees that the user does not need to wait for
80the file to be transferred to disk or to the cloud, and makes it
81durable to transient failures of cloud connectivity.  The provided
82C<sbin/rt-externalize-attachments> script, to be run regularly via cron,
83takes care of moving attachments out of the database at a later time.
84
85=head1 SETUP
86
87=head2 Edit F</opt/rt5/etc/RT_SiteConfig.pm>
88
89You will need to configure the C<%ExternalStorage> option,
90depending on how and where you want your data stored.
91
92RT comes with a number of possible storage backends; see the
93documentation in each for necessary configuration details:
94
95=over
96
97=item L<RT::ExternalStorage::Disk>
98
99=item L<RT::ExternalStorage::Dropbox>
100
101=item L<RT::ExternalStorage::AmazonS3>
102
103=back
104
105=head2 Restart your webserver
106
107Restarting the webserver before the next step (extracting existing
108attachments) is important to ensure that files remain available as they
109are extracted.
110
111=head2 Extract existing attachments
112
113Run C<sbin/rt-externalize-attachments>; this may take some time, depending
114on the existing size of the database.  This task may be safely cancelled
115and re-run to resume.
116
117=head2 Schedule attachments extraction
118
119Schedule C<sbin/rt-externalize-attachments> to run at regular intervals via
120cron.  For instance, the following F</etc/cron.d/rt> entry will run it
121daily, which may be good to concentrate network or disk usage to times
122when RT is less in use:
123
124    0 0 * * * root /opt/rt5/sbin/rt-externalize-attachments
125
126=head1 CAVEATS
127
128This feature is not currently compatible with RT's C<shredder> tool;
129attachments which are shredded will not be removed from external
130storage.
131
132=cut
133
134RT::Base->_ImportOverlays();
135
1361;
137