Cloudera Docs

Commands for using cache pools and directives

You can use the Command Line Interface (CLI) to create, modify, and list cache pools and cache directives using the hdfs cacheadmin subcommand.

Cache Directives are identified by a unique, non-repeating, 64-bit integer ID. IDs will not be reused even if a Cache Directive is removed.

Cache Pools are identified by a unique string name.

You must first create a Cache Pool, and then add Cache Directives to the Cache Pool.

Cache Pool Commands

  • addPool -- Adds a new Cache Pool.

    Usage:

    hdfs cacheadmin -addPool <name> [-owner <owner>] [-group <group>] 
[-mode <mode>] [-limit <limit>] [-maxTtl <maxTtl>]
    Options:
    Table 1. Cache Pool Add Options
    Option Description
    <name> The name of the pool.
    <owner> The user name of the owner of the pool. Defaults to the current user.
    <group> The group that the pool is assigned to. Defaults to the primary group name of the current user.
    <mode> The UNIX-style permissions assigned to the pool. Permissions are specified in octal (for example, 0755). Pool permissions are set to 0755 by default.
    <limit> The maximum number of bytes that can be cached by directives in the pool, in aggregate. By default, no limit is set.
    <maxTtl> The maximum allowed time-to-live for directives being added to the pool. This can be specified in seconds, minutes, hours, and days (e.g. 120s, 30m, 4h, 2d). Valid units are [smhd]. By default, no maximum is set. A value of "never" specifies that there is no limit.

  • modifyPool -- Modifies the metadata of an existing Cache Pool.

    Usage:

    hdfs cacheadmin -modifyPool <name> [-owner <owner>] [-group <group>] 
[-mode <mode>] [-limit <limit>] [-maxTtl <maxTtl>]
    Options:
    Table 2. Cache Pool Modify Options
    Option Description
    <name> The name of the pool to modify.
    <owner> The user name of the owner of the pool.
    <group> The group that the pool is assigned to.
    <mode> The UNIX-style permissions assigned to the pool. Permissions are specified in octal (for example, 0755).
    <limit> The maximum number of bytes that can be cached by directives in the pool, in aggregate.
    <maxTtl> The maximum allowed time-to-live for directives being added to the pool. This can be specified in seconds, minutes, hours, and days (for example, 120s, 30m, 4h, 2d). Valid units are [smdh]. By default, no maximum is set. A value of "never" specifies that there is no limit.

  • removePool -- Removes a Cache Pool. This command also "un-caches" paths that are associated with the pool.

    Usage:

    hdfs cacheadmin -removePool <name>
    Options:
    Table 3. Cache Pool Remove Options
    Option Description
    <name> The name of the Cache Pool to remove.

  • listPools -- Displays information about one or more Cache Pools, such as name, owner, group, permissions, and so on.

    Usage:

    hdfs cacheadmin -listPools [-stats] [<name>]
    Options:
    Table 4. Cache Pools List Options
    Option Description
    -stats Displays additional Cache Pool statistics.
    <name> If specified, lists only the named Cache Pool.

  • help -- Displays detailed information about a command.

    Usage:

    hdfs cacheadmin -help <command-name>
    Options:
    Table 5. Cache Pool Help Options
    Option Description
    <command-name Displays detailed information for the specified command name. If no command name is specified, detailed help is displayed for all commands.

Cache Directive Commands

  • addDirective -- Adds a new Cache Directive.

    Usage:

    hdfs cacheadmin -addDirective -path <path> -pool <pool-name> [-force] 
[-replication <replication>] [-ttl <time-to-live>]
    Options:
    Table 6. Cache Pool Add Directive Options
    Option Description
    <path> The path to the cache directory or file.
    <pool-name> The Cache Pool to which the Cache Directive will be added. You must have Write permission for the Cache Pool in order to add new directives.
    -force Skips checking of the Cache Pool resource limits.
    <replication> The cache replication factor to use. Default setting is 1.
    <time-to-live> How long the directive is valid. This can be specified in minutes, hours and days (for example, 30m, 4h, 2d). Valid units are [smdh]. A value of "never" indicates a directive that never expires. If unspecified, the directive never expires.

  • removeDirective -- Removes a Cache Directive.

    Usage:

    hdfs cacheadmin -removeDirective <id>
    Options:
    Table 7. Cache Pool Remove Directive Options
    Option Description
    <id> The ID of the Cache Directive to remove. You must have Write permission for the pool that the directive belongs to in order to remove it. You can use the -listDirectives command to display a list of Cache Directive IDs.

  • removeDirectives -- Removes all of the Cache Directives in a specified path.

    Usage:

    hdfs cacheadmin -removeDirectives <path>
    Options:
    Table 8. Cache Pool Remove Directives Options
    Option Description
    <path> The path of the Cache Directives to remove. You must have Write permission for the pool that the directives belong to in order to remove them. You can use the -listDirectives command to display a list of Cache Directives.

  • listDirectives -- Returns a list of Cache Directives.

    Usage:

    hdfs cacheadmin -listDirectives [-stats] [-path <path>] [-pool <pool>]
    Options:
    Table 9. Cache Pools List Directives Options
    Option Description
    <path> Lists only the Cache Directives in the specified path. If there is a Cache Directive in the <path> that belongs to a Cache Pool for which you do not have Read access, it will not be listed.
    <pool> Lists on the Cache Directives in the specified Cache Pool.
    -stats Lists path-based Cache Directive statistics.