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 (e.g. 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 (e.g. 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 (e.g. 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 (e.g. 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.