Manticore Search Management Tool

Overview

The Manticore Search Management Tool is a PHP-based CLI application designed as a sidecar for Manticore Search, facilitating high-level authentication tasks such as user and permission management. It interacts with Manticore Search’s configuration and authentication files (auth.json, auth.tmp) to manage users, tokens, passwords, and permissions, supporting both standard and real-time (RT) modes. The tool logs operations to searchd.log.auth and ensures secure file handling with 0600 permissions, as specified in Manticore Search Spec v1.4.0.

Features

• User Management: Add, delete, list users, generate tokens, and update passwords.
• Permission Management: Add, delete, and list permissions with support for actions (e.g., read, write), targets (e.g., table names, *), and budgets.
• RT Mode Support: Handles real-time updates via auth.tmp for integration with Manticore Buddy.
• Secure Operations: Uses file locking (auth.lock) and 0600 permissions for secure file access.
• Logging: Records all operations and errors to searchd.log.auth using Monolog.
• HTTP Status Checks: Verifies Manticore Search instance status via HTTP requests (status codes 200, 400).

Requirements

• PHP >= 7.4
• Composer
• Dependencies:
  • symfony/console:^5.4
  • symfony/filesystem:^5.4
  • guzzlehttp/guzzle:^7.5
  • monolog/monolog:^2.9
• For development:
  • phpunit/phpunit:^9.5
  • slevomat/coding-standard:^8.0
  • squizlabs/php_codesniffer:^3.7

Installation

1. Clone the Repository:

   git clone <repository-url>
   cd manticore-management-tool

2. Install Dependencies:

   composer install

3. Ensure Manticore Search Configuration:

   • Place a manticore.conf file in one of the default locations (/etc/manticoresearch/manticore.conf, /usr/local/etc/manticore.conf, ./manticore.conf) or specify a custom path using the --config option.
   • Example manticore.conf:

     searchd {
         listen = 127.0.0.1:9308:http
         auth = true
     }
     

Usage

Run the CLI tool using:

php src/main.php [options] <command>

Commands

• User Management:

  • Add a user: php src/main.php user add <username>
  • Generate/update token: php src/main.php user token <username>
  • Update password: php src/main.php user password <username>
  • Delete user: php src/main.php user delete <username>
  • List users: php src/main.php user list

• Permission Management:

  • Add permission: php src/main.php permission add --user <username> --action <action> --target <target> --allow <true|false> [--budget <json>]
  • Delete permission: php src/main.php permission delete --user <username> --action <action> --target <target>
  • List permissions: php src/main.php permission list

• Options:

  • -c, --config <path>: Specify the Manticore Search configuration file path.
  • -h, --help: Display help information.

Examples

• Add a user interactively:

  php src/main.php user add admin
  # Prompts for password

• Add a user with piped password:

  echo "mypassword" | php src/main.php user add admin

• Generate a token:

  php src/main.php user token admin

• Add a permission:

  php src/main.php permission add --user admin --action read --target "*" --allow true --budget '{"queries_per_minute":1000}'

• List all permissions:

  php src/main.php permission list

Testing

The project includes a comprehensive test suite covering unit, integration, functional, and error scenarios.

1. Run Tests:

   vendor/bin/phpunit tests/

2. Run Specific Tests:

   vendor/bin/phpunit tests/Unit/ManticoreCommandUnitTest.php
   vendor/bin/phpunit tests/Integration/ManticoreCommandIntegrationTest.php
   vendor/bin/phpunit tests/Functional/ManticoreCommandFunctionalTest.php
   vendor/bin/phpunit tests/Error/ManticoreCommandErrorTest.php

3. Code Quality Checks:

   • Run PHPStan (Level 9):

     vendor/bin/phpstan analyse --level=9

   • Run PHP_CodeSniffer:

     vendor/bin/phpcs --standard=ruleset.xml src tests

   • Fix CodeSniffer issues:

     vendor/bin/phpcbf --standard=ruleset.xml src tests

Code Structure

• src/main.php: Entry point for the CLI application.

• src/Command/ManticoreCommand.php: Handles CLI command execution and user input processing.

• src/Service/AuthService.php: Manages authentication file operations (users, permissions, RT Mode).

• src/Service/HttpService.php: Checks Manticore Search instance status via HTTP.

• tests/: Contains unit, integration, functional, and error tests.

Coding Standards

The project adheres to strict coding standards defined in phpstan.neon (Level 9) and ruleset.xml:

• Strict type declarations (declare(strict_types=1)).
• Alphabetically sorted imports.
• Trailing commas in arrays.
• No forbidden functions (e.g., count, print).
• Maximum line length of 120 characters.
• CamelCaps naming for variables and methods.

Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/your-feature).
3. Commit changes (git commit -m 'Add your feature').
4. Push to the branch (git push origin feature/your-feature).
5. Open a pull request.

Ensure all code passes PHPStan and PHP_CodeSniffer checks.

License

This project is licensed under the MIT License.