LDAP Schema

Overview

The IPA schema commands provide comprehensive API introspection capabilities, enabling administrators and developers to explore the complete structure of the IPA command-line interface, object classes, parameters, and command outputs programmatically. These introspection tools are essential for understanding available commands, discovering parameters, planning automation scripts, and troubleshooting command usage.

The schema topic encompasses several introspection command categories:

Commands (command-find, command-show): Discover and examine IPA CLI commands, including their parameters, required arguments, and available options. Essential for understanding what operations IPA supports and how to invoke them.

Parameters (param-find, param-show): Inspect individual command parameters, including data types, validation rules, and whether parameters are required or optional. Critical for building robust automation scripts that use IPA commands.

Classes (class-find, class-show): Explore IPA object classes and their attributes, revealing the internal structure of IPA objects and their LDAP schema relationships. Useful for understanding object hierarchies and planning schema extensions.

Outputs (output-find, output-show): Examine command output structures, understanding what data each command returns and in what format. Helps parse command results in automation scripts.

Topics (topic-find, topic-show): Browse help topics and documentation built into the IPA CLI. Provides programmatic access to IPA’s built-in documentation.

These introspection capabilities serve multiple purposes: learning the IPA API, discovering new features as IPA evolves, building robust automation that adapts to API changes, troubleshooting command failures, and planning integration with external systems.

Unlike most IPA commands that manage directory objects (users, groups, hosts), schema commands are read-only query operations that inspect IPA’s API metadata. They don’t modify configuration or directory contents—they reveal how to use commands that do.

EXAMPLES

Show user-find details:
ipa command-show user-find
Find user-find parameters:
ipa param-find user-find

Use Cases

Discovering Available Commands

Administrators new to IPA or exploring specific administrative domains need to discover what commands are available for a given object type or operation.

# Find all user-related commands
ipa command-find user
  command-find: user-add
  command-find: user-del
  command-find: user-disable
  command-find: user-enable
  command-find: user-find
  command-find: user-mod
  command-find: user-show
  command-find: user-status
  command-find: user-unlock
  [...]

# Find all commands containing "password"
ipa command-find password
  command-find: ipa passwd
  command-find: pwpolicy-add
  command-find: pwpolicy-del
  command-find: pwpolicy-find
  command-find: pwpolicy-mod
  command-find: pwpolicy-show

# List all available IPA commands
ipa command-find --pkey-only | wc -l
  700+ commands available

Understanding Command Parameters Before Scripting

Before writing automation scripts, developers need to understand exact parameter names, types, and requirements for IPA commands to avoid runtime failures.

# Show all parameters for user-add command
ipa param-find user-add
  param-find: givenname (required)
  param-find: sn (required)
  param-find: uid (optional)
  param-find: userpassword (optional)
  param-find: mail (optional)
  param-find: telephonenumber (optional)
  [...]

# Show detailed information about specific parameter
ipa param-show user-add givenname
  Parameter: givenname
  Type: str
  Required: True
  Multivalue: False

# Discover whether parameter accepts multiple values
ipa param-show user-add sshpubkey
  Parameter: sshpubkey
  Type: str
  Multivalue: True
  # Can specify multiple SSH public keys

Exploring Object Classes for Schema Extensions

When planning custom LDAP schema extensions, administrators need to understand existing IPA object classes and their attributes to avoid conflicts and ensure compatibility.

# List all object classes
ipa class-find --pkey-only
  class-find: user
  class-find: group
  class-find: host
  class-find: service
  class-find: hbacrule
  class-find: sudorule
  [...]

# Show detailed information about user object class
ipa class-show user --all
  Class: user
  Attributes: uid, givenname, sn, cn, displayname, initials, gecos,
              homephone, mobile, pager, facsimiletelephonenumber,
              telephonenumber, street, roomnumber, l, st, postalcode,
              manager, secretary, title, carlicense, labeleduri,
              inetuserhttpurl, seealso, employeetype, businesscategory,
              o, ou, mail, krbprincipalname, uidnumber, gidnumber,
              loginshell, homedirectory, [...]
  # Full attribute list for planning schema extensions

Building Dynamic Command Wrappers

Automation tools building wrappers around IPA commands need to dynamically discover command structure to generate appropriate user interfaces or validation logic.

# Get full command details for wrapper generation
ipa command-show user-add --all
  Command: user-add
  Summary: Add a new user.
  Takes arguments: uid
  Takes options: givenname, sn, cn, displayname, initials, [...]

# For each option, get validation requirements
for param in $(ipa param-find user-add --pkey-only | grep "  " | awk '{print $2}'); do
  echo "Parameter: $param"
  ipa param-show user-add "$param" | grep -E "(Type|Required|Multivalue)"
done
  Parameter: givenname
  Type: str
  Required: True
  Multivalue: False

  Parameter: sn
  Type: str
  Required: True
  Multivalue: False
  [...]
# Build dynamic form or CLI wrapper based on this metadata

Troubleshooting Unknown Command Errors

When encountering errors about unknown commands or parameters (often after upgrades or in mixed-version environments), use introspection to verify command availability.

# Verify command exists in this IPA version
ipa command-show passkey-add
  # If command exists, shows details
  # If not, shows "command not found" error
  # Helps identify version compatibility issues

# Check if parameter is valid for this command
ipa param-find user-mod --pkey-only | grep ipauserauthtype
  param-find: ipauserauthtype
  # Parameter exists - can use --user-auth-type option

# If parameter not found, may be version mismatch or typo
ipa param-find user-mod --pkey-only | grep nonexistent
  # No results - parameter doesn't exist

Documenting Custom IPA Integration

When documenting IPA integration for application teams, generate comprehensive parameter reference documentation programmatically.

# Generate documentation for all user commands
for cmd in $(ipa command-find user --pkey-only | grep "^  " | awk '{print $2}'); do
  echo "## $cmd"
  ipa command-show "$cmd"
  echo ""
  echo "### Parameters"
  ipa param-find "$cmd" --all
  echo ""
done > user_commands_reference.txt

# Document includes:
# - Command summaries
# - All parameters with types and requirements
# - Help text for each command
# Provides complete API reference for integration developers

Validating Automation Scripts Against API Changes

After IPA upgrades, validate that automation scripts still use valid commands and parameters to prevent runtime failures.

# Script validation: check if commands used in scripts exist
for cmd in user-add user-mod group-add-member hbacrule-add sudorule-add; do
  if ipa command-show "$cmd" >/dev/null 2>&1; then
    echo "$cmd: OK"
  else
    echo "$cmd: MISSING - script will fail"
  fi
done
  user-add: OK
  user-mod: OK
  group-add-member: OK
  hbacrule-add: OK
  sudorule-add: OK

# Check if specific parameters still exist
ipa param-find user-mod --pkey-only | grep -q "ipauserauthtype" && \
  echo "ipauserauthtype parameter: OK" || \
  echo "ipauserauthtype parameter: MISSING"

Discovering Command Outputs for Parsing

Automation scripts parsing IPA command output need to understand output structure to extract specific fields reliably.

# Show output structure for user-show command
ipa output-find user-show
  output-find: result
  output-find: summary
  output-find: count
  output-find: truncated

# Show details of specific output field
ipa output-show user-show result
  Output: result
  Type: dict
  # Output is dictionary containing user attributes
  # Scripts can parse JSON output reliably

# Discover available fields in output
ipa user-show admin --all --raw | jq 'keys'
  [
    "cn",
    "displayname",
    "dn",
    "gecos",
    "gidnumber",
    "givenname",
    [...]
  ]
# Use output introspection + jq to understand parsing requirements

Planning Migration Scripts

When migrating from other identity systems to IPA, understand IPA’s object structure and required attributes to design accurate migration mapping.

# Understand required attributes for user creation
ipa param-find user-add | grep -i required
  Parameter: givenname (Required: True)
  Parameter: sn (Required: True)
  # Migration must include first name and last name

# Discover optional attributes for complete migration
ipa class-show user | grep "Attributes:" -A 50
  Attributes: uid, givenname, sn, cn, mail, telephonenumber,
              title, employeetype, manager, [...]

# Map source system attributes to IPA attributes
# Example: SourceSystem.FirstName → IPA.givenname
#          SourceSystem.LastName → IPA.sn
#          SourceSystem.Email → IPA.mail

Finding Help Topics for Learning

New administrators can browse built-in help topics to learn IPA concepts and command usage without leaving the command line.

# List all help topics
ipa topic-find
  topic-find: user
  topic-find: group
  topic-find: host
  topic-find: sudo
  topic-find: hbac
  topic-find: cert
  [...]

# Show help for specific topic
ipa topic-show user
  Topic: user
  Summary: User management commands
  Description: Commands for managing user accounts including
               creation, modification, deletion, enabling, disabling,
               and password management.

# Learn about new features
ipa topic-show passkey
  Topic: passkey
  Summary: Passkey/FIDO2 authentication configuration
  [detailed help text]

Security Considerations

Information disclosure to authenticated users: Schema introspection commands are available to all authenticated users by default, revealing the complete IPA API structure. This discloses what administrative operations are possible, what object types exist, and what attributes can be managed. While not directly exploitable, this information aids attackers in understanding the environment and planning attacks.

Command discovery enables privilege escalation reconnaissance: Attackers with low-privileged access can use command introspection to discover administrative commands they don’t currently have access to, then search for privilege escalation paths to gain those capabilities. Knowing that user-mod --user-auth-type can disable multi-factor authentication guides attackers toward specific privilege escalation targets.

Parameter enumeration reveals validation weaknesses: By examining parameter types and validation rules, attackers can identify potential injection points or validation gaps. For example, discovering that a parameter accepts LDAP filters might reveal filter injection vulnerabilities.

Schema information aids targeted attacks: Understanding object classes and attribute structures helps attackers craft targeted LDAP queries or identify sensitive attributes to target in data exfiltration attacks. Knowledge that userPassword and krbPrincipalKey attributes exist guides attackers toward credential theft.

Output structure analysis enables data extraction: Understanding command output structures helps attackers build efficient data extraction scripts if they gain administrative access. Knowing exactly what fields user-show --all returns optimizes automated credential harvesting.

No rate limiting on introspection queries: Schema commands typically don’t have rate limiting, allowing rapid enumeration of the entire API surface. Attackers can quickly build comprehensive API maps for vulnerability research or attack planning.

Version fingerprinting through command availability: By testing for presence/absence of specific commands, attackers can fingerprint IPA version. Different versions have different vulnerabilities; accurate version identification enables targeted exploit selection.

Custom command exposure: If administrators have added custom commands or modified standard commands, schema introspection reveals these customizations, potentially exposing organization-specific vulnerabilities or weaknesses.

Documentation of privilege paths: Help topics and command descriptions may document which roles or privileges grant access to specific commands, revealing the privilege structure and helping attackers identify targets for privilege escalation.

Automation script reconnaissance: If automation scripts are visible (e.g., in shared repositories), attackers can use schema introspection to understand what those scripts do and how to subvert them, even without direct access to the scripts.

No logging of introspection queries: Schema commands are typically not logged in audit trails since they’re read-only operations. Attackers can perform extensive reconnaissance without generating audit events, delaying detection.

Troubleshooting

Command Not Found Error

Symptom: ipa command-show command-name returns “command not found” error.

Diagnosis: Command doesn’t exist in this IPA version, command name is misspelled, or command has been deprecated.

Resolution: Search for similar command names:

# Search for partial command name
ipa command-find user-
  command-find: user-add
  command-find: user-del
  command-find: user-disable
  [...]

# Check if command was renamed in recent version
ipa command-find password
  command-find: ipa passwd
  # "passwd" instead of "password-change"

# Verify IPA version
ipa --version
  VERSION: 4.12.2
# Check release notes for command availability in this version

Parameter Not Showing Expected Options

Symptom: ipa param-find command-name doesn’t show a parameter that should exist.

Diagnosis: Parameter name is incorrect, parameter is version-specific, or parameter is dynamically generated.

Resolution: Search broadly and check version:

# Search for parameter across all commands
ipa param-find --pkey-only | grep -i authtype
  param-find: user-mod.ipauserauthtype
  # Correct parameter name is ipauserauthtype, not userAuthType

# Verify parameter in specific command
ipa param-find user-mod | grep -i auth
  param-find: ipauserauthtype
  # Confirms parameter exists in user-mod

# Check IPA version for feature availability
ipa --version
  VERSION: 4.9.8
# Feature may not exist in older versions

Class Information Shows Fewer Attributes Than Expected

Symptom: ipa class-show user doesn’t show custom attributes that exist in LDAP schema.

Diagnosis: IPA class introspection only shows IPA-managed attributes, not all LDAP schema attributes.

Resolution: Use LDAP tools to inspect full schema:

# IPA class-show shows IPA-managed attributes
ipa class-show user | grep "Attributes:"
  Attributes: uid, givenname, sn, cn, mail, [IPA-managed list]

# For complete LDAP schema including custom attributes, query directly
ldapsearch -Y GSSAPI -b "cn=schema" "(objectClass=*)" \
  objectClasses attributeTypes | grep -i "employeeNumber"
  attributeTypes: ( 2.16.840.1.113730.3.1.3 NAME 'employeeNumber' ... )
  # Shows complete LDAP schema definition including custom attributes

Output Structure Differs from Introspection

Symptom: ipa output-show command-name result shows one structure, but actual command output differs.

Diagnosis: Output structure varies based on command options (—all, —raw) or IPA version.

Resolution: Test command with different options:

# Check output structure definition
ipa output-show user-show result
  Output: result
  Type: dict

# Test actual output with different options
ipa user-show admin --raw
  # Shows LDAP attribute names (raw format)

ipa user-show admin --all
  # Shows all attributes including operational attributes

ipa user-show admin
  # Shows default filtered output

# Adjust parsing logic based on options used

Topic Help Text Outdated or Incorrect

Symptom: ipa topic-show topic-name shows information that doesn’t match actual command behavior.

Diagnosis: Help text may not be updated with latest command changes, or custom modifications changed behavior without updating help.

Resolution: Verify against actual command behavior:

# Topic says one thing
ipa topic-show sudo
  [description of sudo command usage]

# Test actual command to verify
ipa sudorule-add test-rule --help
  # Shows actual current parameters and options

# Rely on command --help and param-find for accurate info
ipa param-find sudorule-add --all
  # Authoritative parameter list

Cannot Find Newly Added Custom Command

Symptom: Custom plugin added to IPA but ipa command-find doesn’t list it.

Diagnosis: Plugin registration incomplete, server not restarted, or API cache not refreshed.

Resolution: Restart IPA services and clear cache:

# Restart IPA services
ipactl restart

# Clear API schema cache
rm -rf ~/.cache/ipa/schema/*

# Reconnect and retry
kdestroy
kinit admin
ipa command-find custom-command

Param-Find Returns Too Many Results

Symptom: ipa param-find param-name returns parameters from many commands, making it hard to find specific parameter.

Diagnosis: Parameter name search is too broad.

Resolution: Narrow search to specific command:

# Too broad search
ipa param-find mail
  param-find: user-add.mail
  param-find: user-mod.mail
  param-find: group-add.mail
  param-find: host-add.mail
  [hundreds of results]

# Narrow to specific command
ipa param-find user-add mail
  param-find: mail
  # Only parameters from user-add command

# Or use command-show for all params of one command
ipa command-show user-add --all
  [complete parameter list for user-add]

Schema Commands Work But Show No Data

Symptom: Schema commands execute without error but return empty results or minimal data.

Diagnosis: May need —all flag to see complete metadata.

Resolution: Add —all flag for comprehensive output:

# Without --all, output is minimal
ipa class-show user
  Class: user
  [basic info only]

# With --all, shows complete details
ipa class-show user --all
  Class: user
  Attributes: [complete list]
  Parent object classes: [inheritance]
  Object class: [LDAP objectClass values]
  [comprehensive metadata]

Command-Show Displays Unexpected Results

Symptom: ipa command-show output doesn’t match command’s actual —help text.

Diagnosis: Differences between API metadata and CLI help text implementation.

Resolution: Trust command —help as authoritative:

# command-show may show API-level details
ipa command-show user-add
  [API metadata representation]

# CLI --help shows actual user-facing interface
ipa user-add --help
  Usage: ipa user-add LOGIN [options]
  [actual CLI usage and options]

# Use --help for scripting, command-show for API understanding

Permission Denied When Running Schema Commands

Symptom: Schema introspection commands fail with “Insufficient access” errors.

Diagnosis: Not authenticated or authentication expired.

Resolution: Verify Kerberos authentication:

# Check Kerberos ticket
klist
  # If no ticket or expired:

# Authenticate
kinit admin

# Retry schema command
ipa command-find user
  # Should succeed after authentication

Class-Show Shows Different Attributes After Upgrade

Symptom: After IPA upgrade, ipa class-show returns different attribute lists than before.

Diagnosis: IPA version upgrade added new managed attributes or changed schema.

Resolution: Review upgrade release notes and verify schema:

# Check new attributes
ipa class-show user --all > /tmp/user-class-new.txt

# Compare with previous version's output (if saved)
diff /tmp/user-class-old.txt /tmp/user-class-new.txt
  > ipauserauthtype
  > ipatokenradiusconfig
  # New attributes added in upgrade

# Review release notes for new features
# Update automation scripts to handle new attributes

Output-Find Shows No Results for Known Command

Symptom: ipa output-find command-name returns no results even though command exists and has output.

Diagnosis: Not all commands have formally defined output structures in the introspection API.

Resolution: Use command with —all —raw for output discovery:

# output-find may not have metadata
ipa output-find obscure-command
  0 outputs found

# Run command to discover actual output structure
ipa obscure-command --all --raw
  # Examine actual output structure

# Parse JSON output programmatically
ipa obscure-command --all --raw | jq 'keys'
  # Discover output fields

Param-Show Indicates Required But Command Works Without It

Symptom: ipa param-show says parameter is required, but command succeeds without providing it.

Diagnosis: Parameter may have default value or conditional requirement.

Resolution: Test command behavior and check for defaults:

# param-show indicates required
ipa param-show user-add uid
  Parameter: uid
  Required: False
  # Actually not required - defaults to givenname

# Test without parameter
ipa user-add testuser --first=Test --last=User
  # Succeeds without explicit --uid
  # uid defaulted to "testuser"

# Check command output for applied defaults
ipa user-show testuser | grep "User login"
  User login: testuser
  # Default was applied

Cannot Determine Valid Values for Parameter

Symptom: Need to know valid values for a parameter but param-show doesn’t list them.

Diagnosis: Parameter accepts free-form input or valid values are context-dependent.

Resolution: Check command help text and try invalid value to see error:

# param-show doesn't list valid values
ipa param-show user-mod ipauserauthtype
  Parameter: ipauserauthtype
  Type: str
  Multivalue: True

# Try command with --help
ipa user-mod --help | grep -A5 "user-auth-type"
  --user-auth-type=LIST  Types of supported user authentication
                         (password, radius, otp, pkinit, hardened,
                         idp, passkey, disabled)

# Or try invalid value to see error message
ipa user-mod testuser --user-auth-type=invalid
  ipa: ERROR: invalid 'ipauserauthtype': must be one of
  password, radius, otp, pkinit, hardened, idp, passkey, disabled

Topic-Show Displays “Topic Not Found”

Symptom: ipa topic-show topic-name fails with “topic not found” even for standard topics.

Diagnosis: Topic name is incorrect or feature doesn’t have a help topic.

Resolution: List all topics and search:

# List all available topics
ipa topic-find --pkey-only
  topic-find: user
  topic-find: group
  topic-find: hbac
  topic-find: sudo
  [...]

# Search for related topics
ipa topic-find password
  topic-find: passwd
  # Topic is "passwd", not "password"

# Show correct topic
ipa topic-show passwd
  [help text for password management]

Commands

class-find

Usage: ipa [global-options] class-find [CRITERIA] [options]

Search for classes.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--pkey-only`	Results should contain primary key attribute only (“name”)

class-show

Usage: ipa [global-options] class-show FULL-NAME [options]

Display information about a class.

Arguments

Argument	Required	Description
`FULL-NAME`	yes	Full name

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

command-find

Usage: ipa [global-options] command-find [CRITERIA] [options]

Search for commands.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--pkey-only`	Results should contain primary key attribute only (“name”)

command-show

Usage: ipa [global-options] command-show FULL-NAME [options]

Display information about a command.

Arguments

Argument	Required	Description
`FULL-NAME`	yes	Full name

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

output-find

Usage: ipa [global-options] output-find COMMAND [CRITERIA] [options]

Search for command outputs.

Arguments

Argument	Required	Description
`COMMAND`	yes	Full name

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--pkey-only`	Results should contain primary key attribute only (“name”)

output-show

Usage: ipa [global-options] output-show COMMAND NAME [options]

Display information about a command output.

Arguments

Argument	Required	Description
`COMMAND`	yes	Full name

NAME yes Name

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

param-find

Usage: ipa [global-options] param-find METAOBJECT [CRITERIA] [options]

Search command parameters.

Arguments

Argument	Required	Description
`METAOBJECT`	yes	Full name

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--pkey-only`	Results should contain primary key attribute only (“name”)

param-show

Usage: ipa [global-options] param-show METAOBJECT NAME [options]

Display information about a command parameter.

Arguments

Argument	Required	Description
`METAOBJECT`	yes	Full name

NAME yes Name

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

topic-find

Usage: ipa [global-options] topic-find [CRITERIA] [options]

Search for help topics.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.
`--pkey-only`	Results should contain primary key attribute only (“name”)

topic-show

Usage: ipa [global-options] topic-show FULL-NAME [options]

Display information about a help topic.

Arguments

Argument	Required	Description
`FULL-NAME`	yes	Full name

Options

Option	Description
`--all`	Retrieve and print all attributes from the server. Affects command output.
`--raw`	Print entries as stored on the server. Only affects output format.

Overview

Use Cases

Discovering Available Commands

Understanding Command Parameters Before Scripting

Exploring Object Classes for Schema Extensions

Building Dynamic Command Wrappers

Troubleshooting Unknown Command Errors

Documenting Custom IPA Integration

Validating Automation Scripts Against API Changes

Discovering Command Outputs for Parsing

Planning Migration Scripts

Finding Help Topics for Learning

Security Considerations

Troubleshooting

Command Not Found Error

Parameter Not Showing Expected Options

Class Information Shows Fewer Attributes Than Expected

Output Structure Differs from Introspection

Topic Help Text Outdated or Incorrect

Cannot Find Newly Added Custom Command

Param-Find Returns Too Many Results

Schema Commands Work But Show No Data

Command-Show Displays Unexpected Results

Permission Denied When Running Schema Commands

Class-Show Shows Different Attributes After Upgrade

Output-Find Shows No Results for Known Command

Param-Show Indicates Required But Command Works Without It

Cannot Determine Valid Values for Parameter

Topic-Show Displays “Topic Not Found”

Commands

class-find

Arguments

Options

class-show

Arguments

Options

command-find

Arguments

Options

command-show

Arguments

Options

output-find

Arguments

Options

output-show

Arguments

Options

param-find

Arguments

Options

param-show

Arguments

Options

topic-find

Arguments

Options

topic-show

Arguments

Options

Related Topics