NAME

ipaimport - Import textual data into an IPA data store

SYNOPSIS

  ipaimport --catalog CATALOG_NAME --type CATALOG_TYPE
        --start=START_TIME] [--end=END_TIME
        [--description=DESCRIPTION] [--delimiter=DELIM]
        [--append]
        [--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. The '.' character in catalog names can be used to establish a catalog hierarchy, such that the foo.bar catalog is considered a child of the foo catalog. This can be useful for organizing IP data into different categories, semgenting host data by department/functional area, etc.

--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. See TIME RANGES below for more information on how time ranges are used in IPA.

--end=END_TIME

Specifies the end of the time range for which the imported data is valid. See TIME RANGES below for more information on how time ranges are used in IPA.

--append

If this switch is provided, records should be appended to an existing dataset. The time period for the dataset to be selected is specified by the --start and --end options above.

--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.

TIME RANGES

Datasets in an IPA catalog are assigned a time range that 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.

The timestamp format for the --start and --end arguments is YYYY/MM/DD[:HH[:MM[:SS]]]. If the hours, minutes, or seconds are not specified, they are assumed to be zero (the beginning of the day, hour, or minute, respectively.)

In lieu of a timestamp, the --start and --end switches can take a special value of '...' (three dots). These represent "the beginning of time" and "the end of time" respectively, so that the time ranges can have infinite endpoints. In the case where both the --start and end switches are '...', the dataset is considered valid no matter what time period is queried.

Time ranges should be treated as left-closed, right-open intervals. This means that, whereas the --begin timestamp is part of the dataset's time range, the --end switch timestamp is not actually included in the range, but everything prior to it is. See the EXAMPLES section for further clarification.

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:

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.

EXAMPLES

To import IP set data into a "set" catalog that is valid for the month of January, 2009:

  $ ipaimport --catalog testset --type set \
      --start 2009/01/01 --end 2009/02/01 test.2009-01.set.in

To import the following month's data into the same catalog:

  $ ipaimport --catalog testset --type set \
      --start 2009/02/01 --end 2009/03/01 test.2009-02.set.in

To import Bag data for all dates prior to 2009:

  $ ipaimport --catalog testbag --type bag \
      --start ... --end 2009/01/01 test.bag.in

To import prefix map data for the year 2009 and beyond:

  $ ipaimport --catalog testpmap --type pmap  \
      --start 2009/01/01 --end ... 
      test.pmap.in

To import multimap data valid for any given time:

  $ ipaimport --catalog testmmap --type mmap \
      --start ... --end ... \
      test.mmap.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.

SEE ALSO

ipaexport(1), ipaquery(1)