Traffic Server
  1. Traffic Server
  2. TS-764

Traffic Server does not ship any documentation

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 2.1.8
    • Fix Version/s: None
    • Component/s: Documentation
    • Labels:
      None

      Description

      A major problem for ATS to the unskilled user as of today is, there is no on-line documentation besides the (somewhat scarce) information from the home page is available. In particular ATS misses

      • first of all: man pages
      • Description of command line switches (if any), including an interactive help, e.g. the common "h/-help" switch.
      • Description of the used environment, e.g. $TS_ROOT where applicable.

      I think this would be an important release goal for the 3.0 release since that branch is intended for productive use, not by developers. If someone provides me the information or has all needed information in a written form, I could assist to provide man pages.

      I'm aware there is some documentation for traffic_shell commands. I'm unsure if the documentation there reflects the most recent development and is generally up to date. If it is still suitable for ATS as of today, it should be merged with any newly created documentation. As a remark: I remember there was some discussion in the past, where to install the man pages because of the rather generic names, for example "enable", "disable", "exit", ...

        Activity

        Hide
        Leif Hedstrom added a comment -

        First, there's an extensive administrators guide available, see http://trafficserver.apache.org/docs.html . Granted, this is not entirely up to do, but there's a huge effort being made right now by Igor Galic and Alan to get this migrated to the Apache CMS. I'm sure they would welcome more help here.

        1) Yes, man pages would be good for traffic_server, traffic_cop and traffic_manager. There is a "man" page directory in doc/man.

        2) Both traffic_server and traffic_manager provides such a help option. e.g.

        root@loki 294/0 # ./bin/traffic_server  -h
        [TrafficServer] using root directory '/opt/ats'
        Usage: ./bin/traffic_server [--SWITCH [ARG]]
          switch__________________type__default___description
          -l, --lock_memory       int   0         Lock process in memory (must be root)
          -n, --net_threads       int   8         Number of Net Threads
          -Z, --cluster_threads   int   1         Number of Cluster Threads
          -U, --udp_threads       int   1         Number of UDP Threads
          -a, --accept_thread     tog   false     Use an Accept Thread
          -b, --accept_till_done  tog   true      Accept Till Done
          -p, --httpport          int   0         Port Number for HTTP Accept
          -A, --acceptfds         str   (null)    File Descriptor List for Accept
          -P, --cluster_port      int   0         Cluster Port Number
          -o, --dprintf_level     int   0         Debug output level
          -V, --version           tog   false     Print Version String
          -T, --debug_tags        str   (null)    Vertical-bar-separated Debug Tags
          -B, --action_tags       str   (null)    Vertical-bar-separated Behavior Tags
          -i, --interval          int   0         Statistics Interval
          -M, --remote_management tog   false     Remote Management
          -d, --management_dir    str   /opt/at.. Management Directory
          -C, --command           str   (null)    Maintenance Command to Execute
          -k, --clear_hostdb      on    false     Clear HostDB on Startup
          -K, --clear_cache       on    false     Clear Cache on Startup
          -v, --vingid            str   (null)    Vingid Flag
          -c, --read_core         str   (null)    Read Core file
          - , --accept_mss        int   0         MSS for client connections
          -t, --poll_timeout      int   10        poll timeout in milliseconds
          -h, --help                              HELP!
        

        3) The environment is not well tested / supported I think, but yeah, we could add something in the man page to traffic_server about it (and the real docs as well).

        Show
        Leif Hedstrom added a comment - First, there's an extensive administrators guide available, see http://trafficserver.apache.org/docs.html . Granted, this is not entirely up to do, but there's a huge effort being made right now by Igor Galic and Alan to get this migrated to the Apache CMS. I'm sure they would welcome more help here. 1) Yes, man pages would be good for traffic_server, traffic_cop and traffic_manager. There is a "man" page directory in doc/man. 2) Both traffic_server and traffic_manager provides such a help option. e.g. root@loki 294/0 # ./bin/traffic_server -h [TrafficServer] using root directory '/opt/ats' Usage: ./bin/traffic_server [--SWITCH [ARG]] switch__________________type__default___description -l, --lock_memory int 0 Lock process in memory (must be root) -n, --net_threads int 8 Number of Net Threads -Z, --cluster_threads int 1 Number of Cluster Threads -U, --udp_threads int 1 Number of UDP Threads -a, --accept_thread tog false Use an Accept Thread -b, --accept_till_done tog true Accept Till Done -p, --httpport int 0 Port Number for HTTP Accept -A, --acceptfds str ( null ) File Descriptor List for Accept -P, --cluster_port int 0 Cluster Port Number -o, --dprintf_level int 0 Debug output level -V, --version tog false Print Version String -T, --debug_tags str ( null ) Vertical-bar-separated Debug Tags -B, --action_tags str ( null ) Vertical-bar-separated Behavior Tags -i, --interval int 0 Statistics Interval -M, --remote_management tog false Remote Management -d, --management_dir str /opt/at.. Management Directory -C, --command str ( null ) Maintenance Command to Execute -k, --clear_hostdb on false Clear HostDB on Startup -K, --clear_cache on false Clear Cache on Startup -v, --vingid str ( null ) Vingid Flag -c, --read_core str ( null ) Read Core file - , --accept_mss int 0 MSS for client connections -t, --poll_timeout int 10 poll timeout in milliseconds -h, --help HELP! 3) The environment is not well tested / supported I think, but yeah, we could add something in the man page to traffic_server about it (and the real docs as well).
        Hide
        Leif Hedstrom added a comment -

        Moving these all to a "Doc 3.x" release version.

        Show
        Leif Hedstrom added a comment - Moving these all to a "Doc 3.x" release version.
        Hide
        James Peach added a comment -

        I just committed skeleton man pages in fa3a5625795db47b0c53cb156f15610cfd6d70ad.

        Show
        James Peach added a comment - I just committed skeleton man pages in fa3a5625795db47b0c53cb156f15610cfd6d70ad.
        Hide
        Leif Hedstrom added a comment -

        I'm going to mark this as fixed. We are now including all Sphinx docs in the source ball, some man pages etc. I think it's better to file or add docs to more specific bugs as appropriate.

        Feel free to reopen if you disagree.

        Show
        Leif Hedstrom added a comment - I'm going to mark this as fixed. We are now including all Sphinx docs in the source ball, some man pages etc. I think it's better to file or add docs to more specific bugs as appropriate. Feel free to reopen if you disagree.
        Hide
        James Peach added a comment -

        Although, the man pages are currently skeletons, and none of the docs are actually shipped with the product (ie. not installed) ...

        Show
        James Peach added a comment - Although, the man pages are currently skeletons, and none of the docs are actually shipped with the product (ie. not installed) ...

          People

          • Assignee:
            Unassigned
            Reporter:
            Arno Toell
          • Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development