NAME

ipaimport - Import textual data into an IPA data store

SYNOPSIS

  ipaimport --catalog CATALOG_NAME --type CATALOG_TYPE
        [--description=DESCRIPTION] [--delimiter=DELIM]
        [--start=START_TIME] [--end=END_TIME]
        [--db=DB_URI] [--progress=NUM] INPUT_FILE

DESCRIPTION

ipaimport reads IP addresses (and optionally values associated with those IP addresses) and imports them into an IPA catalog.

OPTIONS

--catalog=CATALOG_NAME

Specifies the name of the IPA catalog to import into. If the catalog does not already exist in the IPA data store, it will be created. This option is required.

--type=CATALOG_TYPE

Selects the type of the IPA catalog to be imported into. Valid catalog types are:

set: An IPSet catalog. This is simply a set of IP ranges with no associated values.
bag: A Bag (multiset) catalog. This is a set of IP ranges with associated integer values.
pmap: A prefix map catalog. This is a set of IP ranges with associated textual labels.
mmap: A multimap catalog. This is an extension of the prefix map type where ranges can have multiple labels, and each range-label pair has an associated integer value.

--description=DESCRIPTION

An optional text description of the catalog's contents. This description will be stored in the database and will be visible when querying available catalogs with the ipaquery tool.

--delimiter=DELIM

Specifies the character used as a field delimiter in the input file. By default, ipaimport uses whitespace as the field delimiter.

--start=START_TIME

Specifies the beginning of the time range for which the imported data is valid. The expected format of this option is YYYY/MM/DD[:HH[:MM[:SS]]]. This switch (and the b<--end> switch below) are optional; see TIME RANGES for details.

--end=END_TIME

Specifies the end of the time range for which the imported data is valid. The expected format of this option is YYYY/MM/DD[:HH[:MM[:SS]]]. This switch (and the b<--start> switch above) are optional; see TIME RANGES for details.

--db=DB_URI

A URI specifying the IPA data store to connect to. Due to the possible exposure of database credentials via process listings, the use of this option is discouraged. See ENVIRONMENT below for the recommended way of specifying the IPA data store URI.

--progress=NUM

Print a progress marker every NUM imported records.

INPUT FORMATS

The expected format of the input file depends on the type of the catalog. For all catalog types, "IP range" is defined as an IP address or range of addresses in any of the following formats:

single dotted quad address: 192.168.1.0
single integer address: 3232235776
dotted quad address range: 192.168.1.0-192.168.1.255
integer address range: 3232235776-3232236031
CIDR block: 192.168.1.0/24
CIDR block with int addr: 3232235776/24

For IP set catalogs, the input format is simply one IP range per line:

  4.0.0.0/8
  5.0.0.0/8

For Bag (multiset) catalogs, the input format is an IP range and an integer value, delimited by either whitespace or the --delimiter character:

  4.0.0.0/8 100
  5.0.0.0/8 30

For prefix map catalogs, the input format is an IP range and a textual label associated with that range, delimited by either whitespace or the --delimiter character:

  4.0.0.0/8 foo
  5.0.0.0/8 bar

For multimap catalogs, the input format is an IP range, a textual label, and an integer value, delimited by either whitespace or the --delimiter character:

  4.0.0.0/8 foo 64
  4.0.0.0/8 bar 1
  5.0.0.0/8 foo 0
  5.0.0.0/8 bar 99
  5.0.0.0/8 baz 3
  
Note that the multimap catalog type is the only type where IP ranges
can be duplicated.

TIME RANGES

Data imported into an IPA catalog can have an optional time range which specifies the time during which the data is considered valid. Time ranges cannot overlap, and any attempts to import data with a time range that is already covered within the chosen catalog will produce an error.

When a time range is provided on import, the data is considered valid only during that time period, and only queries which request a time within that time range will return data from the imported data set.

If no such time range is specified on import, the imported data set is considered the "no time" data set for that catalog, and will be returned for all IPA queries which do not contain a time specification.

If a catalog already has a "no time" data set, and you import another data set without a time range, this imported data will replace the existing "no time" data set.

EXAMPLES

To import IP set data into a "set" catalog with no time information:

  $ ipaimport --catalog testset --type set test.set.in

To import Bag data into a "bag" catalog with time range:

  $ ipaimport --catalog testbag --type bag \
      --start 2007/04/01 --end 2007/04/30:23:59:59 \
      --type bag test.bag.in

To import prefix map data into a "pmap" catalog with time range:

  $ ipaimport --catalog testpmap --type pmap \
      --start 2007/05/01 --end 2007/05/31:23:59:59 \
      --type pmap test.pmap.in

ENVIRONMENT

IPA_DB_URI

A URI specifying the location of (and credentials for) the IPA data store. The format of this URI is driver://user:password@hostname/database, e.g.:

    postgresql://ipauser:secret@database-server.domain.com/ipa

NOTES

Currently, only the PostgreSQL database driver is supported.

In version 0.3.0 and earlier, a syntax of a.b.c.x-y was supported for IP ranges. Support for this syntax has been dropped due to its ambiguous nature, given that we also accept integer input for addresses.