#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#

description: |
  The `pulsar` tool is used to start Pulsar components, such as [bookies](#pulsar-bookie) and [ZooKeeper](#pulsar-zookeeper), in the foreground.

  These processes can also be started in the background, using [nohup](https://en.wikipedia.org/wiki/Nohup), using the [`pulsar-daemon`](#pulsar-daemon) tool, which has the same command interface as `pulsar`.
example: |
  pulsar broker \
    --conf /path/to/broker.conf
commands:
- name: bookie
  description: Starts up a bookie server
  example: |
    pulsar bookie \
      -readOnly \
      -withAutoRecovery \
      --conf /path/to/bookkeeper.conf
  options:
  - flags: -c, --conf
    description: Configuration for the bookie server
  - flags: -readOnly
    description: Force start a read-only bookie server
    default: 'false'
  - flags: -withAutoRecovery
    description: Start auto-recovery service bookie server
    default: 'false'
- name: broker
  description: Starts up a Pulsar broker
  example: |
    pulsar broker \
      --conf /path/to/broker.conf
  options:
  - flags: -c, --broker-conf
    description: Configuration file for the broker
  - flags: -bc, --bookie-conf
    description: Configuration file for BookKeeper
  - flags: -rb, --run-bookie
    description: Run a BookKeeper bookie on the same host as the Pulsar broker
    default: 'false'
  - flags: -ra, --run-bookie-autorecovery
    description: Run a BookKeeper autorecovery daemon on the same host as the Pulsar broker
    default: 'false'
- name: compact-topic
  description: Run compaction against a Pulsar topic (in a new process)
  example: |
    pulsar compact-topic \
      --topic topic-to-compact
  options:
  - flags: -t, --topic
    description: The Pulsar topic that you would like to compact
  - flags: -c, --broker-conf
    description: Configuration file for the broker
    default: ${pulsarDirectory}/conf/broker.conf
- name: discovery
  description: Run a discovery server
  example: |
    pulsar discovery \
      --conf /path/to/discovery.conf
  options:
  - flags: -c, --conf
    description: Configuration file for the discovery service
- name: configuration-store
  description: Starts up the Pulsar configuration store
  options:
  - flags: -c, --conf
    description: Configuration file for the configuration store
- name: initialize-cluster-metadata
  description: One-time cluster metadata initialization
  options:
  - flags: -ub, --broker-service-url
    description: The broker service URL for the new cluster
  - flags: -tb, --broker-service-url-tls
    description: The broker service URL for the new cluster with TLS encryption
  - flags: -c, --cluster
    description: Cluster name
  - flags: --configuration-store
    description: The configuration store quorum connection string
  - flags: -uw, --web-service-url
    description: The web service URL for the new cluster
  - flags: -tw, --web-service-url-tls
    description: The web service URL for the new cluster with TLS encryption
  - flags: -zk, --zookeeper
    description: The local ZooKeeper quorum connection string
- name: proxy
  description: Manages the Pulsar proxy
  example: |
    pulsar proxy \
      --zookeeper-servers zk-0,zk-1,zk2 \
      --configuration-store zk-0,zk-1,zk-2
  options:
  - flags: -c, --config
    description: Path to a Pulsar proxy configuration file
  - flags: --configuration-store
    description: Configuration store connection string
  - flags: -zk, --zookeeper-servers
    description: Local ZooKeeper connection string
- name: standalone
  description: Run a broker service with local bookies and local ZooKeeper
  options:
  - flags: -a, --advertised-address
    description: The standalone broker advertised address
  - flags: --bookkeeper-dir
    description: Local bookies' base data directory
    default: data/standalone/bookeeper
  - flags: --bookkeeper-port
    description: Local bookies' base port
    default: 3181
  - flags: -c, --config
    description: Configuration file path
  - flags: --no-broker
    description: Only start ZooKeeper and BookKeeper services, not the broker
    default: 'false'
  - flags: --num-bookies
    description: The number of local bookies
    default: 1
  - flags: --only-broker
    description: Only start the Pulsar broker service (not ZooKeeper or BookKeeper)
    default: false
  - flags: --wipe-data
    description: Clean up previous ZooKeeper/BookKeeper data
    default: false
  - flags: --zookeeper-dir
    description: Local ZooKeeper's data directory
    default: data/standalone/zookeeper
  - flags: --zookeeper-port
    description: Local ZooKeeper's port
    default: 2181
- name: websocket
  options:
  - flags: -c, --conf
    description: Configuration file for WebSocket service
- name: zookeeper
  description: Starts up a ZooKeeper cluster
  options:
  - flags: -c, --conf
    description: Configuration file for ZooKeeper
- name: zookeeper-shell
  description: Connects to a running ZooKeeper cluster using the ZooKeeper shell
  options:
  - flags: -c, --conf
    description: Configuration file for ZooKeeper
- name: zookeeper-shell
  description: Opens up a shell client to the ZooKeeper cluster used by Pulsar
env_vars:
- name: PULSAR_LOG_CONF
  description: Log4j configuration file
  default: conf/log4j2.yaml
- name: PULSAR_BROKER_CONF
  description: Configuration file for broker
  default: conf/broker.conf
- name: PULSAR_BOOKKEEPER_CONF
  description: Configuration file for bookie
  default: conf/bookkeeper.conf
- name: PULSAR_ZK_CONF
  description: Configuration file for zookeeper
  default: conf/zookeeper.conf
- name: PULSAR_CONFIGURATION_STORE_CONF
  description:  Configuration file for the configuration store
  default: conf/global_zookeeper.conf
- name: PULSAR_DISCOVERY_CONF
  description: Configuration file for discovery service
  default: conf/discovery.conf
- name: PULSAR_WEBSOCKET_CONF
  description: Configuration file for websocket proxy
  default: conf/websocket.conf
- name: PULSAR_STANDALONE_CONF
  description: Configuration file for standalone
  default: conf/standalone.conf
- name: PULSAR_EXTRA_OPTS
  description: Extra options to be passed to the jvm
- name: PULSAR_EXTRA_CLASSPATH
  description: Extra paths for Pulsar's classpath
- name: PULSAR_PID_DIR
  description: Folder where the pulsar server PID file should be stored
- name: PULSAR_STOP_TIMEOUT
  description: Wait time before forcefully killing the Bookie server instance if attempts to stop it are not successful
