=head1 NAME

ngcp-keydb-backup - import and export KeyDB location entries

=head1 SYNOPSIS

B<ngcp-keydb-backup> I<OPERATION> [I<OPTION>...]

=head1 DESCRIPTION

This program imports or exports KeyDB location data via a JSON intermediate,
optionally manipulating or converting the entries in the process.

=head1 OPERATIONS

=over 4

=item B<export>

Reads location entries from the KeyDB database and dumps them in JSON format.

=item B<import>

Reads location entries in JSON format and writes them into the KeyDB database.

=back

=head1 OPTIONS

=over 4

=item B<-h>, B<--help>

Prints the usage summary.

=item B<--ip=>I<IP>

IP address or host name of the KeyDB server to connect to. Defaults to
B<localhost>.

=item B<--port=>I<PORT>

Port number of the KeyDB server to connect to. Defaults to B<6379>.

=item B<--db=>I<DB>

KeyDB database number to read from or write to. Defaults to B<20>.

=item B<--file=>I<FILE>

When importing: file to read the JSON data from. When exporting: file to write
the JSON data to. Defaults to stdin or stdout if not specified.

=item B<--flushdb>

When importing, flush the KeyDB DB before importing the records. It is an error
if there are existing entries in the KeyDB DB and neither B<--flushdb> nor
B<--merge> is specified.

=item B<--merge>

When importing, merge imported entries with existing entries in the KeyDB DB,
possibly overwriting them. It is an error if there are existing entries in the
KeyDB DB and neither B<--flushdb> nor B<--merge> is specified.

=item B<--overwrite>

When exporting, allow overwriting an output JSON file if it already exists.

=item B<--permanent=>B<only>|B<exclude>

Filter permanent registrations. Either import or export only permanent
registrations (B<only>), or import or export only non-permanent registrations
(B<exclude>).

=item B<--shift-expiry=>I<TIMESPAN>

Shift the expiry time of non-permanent location records forward (into the
future) by the given time span. Examples or valid time spans are B<30s>, B<3h>,
B<5d>, or a combination thereof, such as B<1h30m>. This option can be used for
both imports and exports.

=item B<--set-expiry=>I<TIMESPAN>

Set the expiry time of non-permanent location records to the current time plus
the given time span (into the future). See B<--shift-expiry> for a description
of valid time spans. This option can be used for both imports and exports.

=item B<--version=>B<0>|B<1>

Specify the KeyDB DB schema version when importing from or exporting to the
KeyDB DB. The default is auto-detected from the Kamailio config file.

=back

=head1 EXIT STATUS

Exit code 0 means everything is fine, 1 means an error occurred, and 2
indicates a usage error.

=head1 BUGS AND LIMITATIONS

Please report problems you notice to the Sipwise
Development Team <support@sipwise.com>.

=head1 AUTHOR

Richard Fuchs <rfuchs@sipwise.com>

=head1 LICENSE

Copyright (C) 2021 Sipwise GmbH, Austria

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
