Работа с документацией

Зачастую документация Вам нужна для того, чтобы понять, как пользоваться всеми этими многочисленными программами, и один из самых частных и важных случаев — разобраться, какие аргументы нужно указывать в командной строке.

Корректное использование программ во многом зависит от того, насколько правильно Вы задаёте аргументы. Вспомните флаг -a в команде ls -a из задания про скрытые файлы прошлого модуля: этот -a был аргументом, который говорил ls выводить и скрытые файлы, и обычные. Поскольку мы хотели увидеть скрытые файлы, вызов ls с аргументом -a был правильным способом использовать эту команду в нашей ситуации.

В этом задании/challenge/run принимает особый аргумент. Вам нужно корректно вызвать программу, чтобы она выдала флаг.

Представим, что её документация выглядит так:

Добро пожаловать в документацию к /challenge/run! Чтобы правильно запустить эту программу, Вам нужно передать ей аргумент --giveflag. Удачи!

Имея эту информацию, идите и получите флаг!

Хотя использование большинства команд вполне очевидно, синтаксис некоторых может быть довольно сложным.

Например:
Аргументы к таким утилитам, как sed и awk (мы сейчас не будем углубляться в них), сами по себе являются целыми программами на своеобразном языке!

Где‑то посередине между простотой cd и сложностью awk находятся команды, у которых аргументы зависят от других аргументов... Такими командами с цепочкой аргументов настраиваются правила сетевого взаимодействия в Linux или осуществляется управление пакетами (наборы ПО, расширяющие функционал системы). Мы будем знакомиться с таким подходом далее, а сейчас рассмотрим классический пример, когда у аргумента есть значение.

Вы уже сталкивались с подходом «ключ–значение» в задании про find в предыдущем модуле. У find есть аргумент -name, и сам этот аргумент -name принимает в качестве значения имя, по которому нужно выполнять поиск. Многие другие команды устроены аналогичным образом. Давайте освоим этот подход на практике.

Вот документация к /challenge/run для этого уровня:

Добро пожаловать в документацию по /challenge/run! Эта программа позволяет выводить произвольные файлы в терминал (без ограничений доступа), если ей передан аргумент --printfile. Аргументом к --printfile является путь к файлу с флагом, который нужно прочитать. Например, команда /challenge/run --printfile /etc/passwd выведет список пользователей системы!

Имея такую документацию, идите и получите флаг!

В этом модуле Вам предстоит освоить команду man (мы уже рекомендовали вам ее ранее).

man — сокращение от manual, и эта команда отображает (если онf есть) инструкцию по использованию команды, имя которой Вы передаёте ей в качестве аргумента.

Например, допустим, мы хотим узнать больше о команде yes (да, такая команда действительно существует):

hacker@man:~$ man yes

Это вызовет отображение справочной страницы (man‑страницы) для yes, которая будет выглядеть примерно так:

YES(1)                           User Commands                          YES(1)

NAME
       yes - output a string repeatedly until killed

SYNOPSIS
       yes [STRING]...
       yes OPTION

DESCRIPTION
       Repeatedly output a line with all specified STRING(s), or 'y'.

       --help display this help and exit

       --version
              output version information and exit

AUTHOR
       Written by David MacKenzie.

REPORTING BUGS
       GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
       Report any translation bugs to <https://translationproject.org/team/>

COPYRIGHT
       Copyright  ©  2020  Free Software Foundation, Inc.  License GPLv3+: GNU
       GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
       This is free software: you are free  to  change  and  redistribute  it.
       There is NO WARRANTY, to the extent permitted by law.

SEE ALSO
       Full documentation <https://www.gnu.org/software/coreutils/yes>
       or available locally via: info '(coreutils) yes invocation'

GNU coreutils 8.32               February 2022                          YES(1)

Вся справка изначально выпускается на Английском языке, но существует большое колличество команд энтузиастов совершающих перевод документации. В рамках ОС Linux есть и РФ сообщество, для знакомства с результатом работы которого требуется использовать ключ -L со значением ru. Вот пример русскоязычной справки:

hacker@man:~$ man -L ru man

Результатом будет отображение справочной страницы для man на русском языке:

MAN(1)                  Утилиты просмотра справочных страниц                  MAN(1)

НАЗВАНИЕ
       man - доступ к системным справочным страницам

СИНТАКСИС
       man [параметры man] [[раздел] страница ...] ...
       man -k [параметры apropos] регвыр ...
       man -K [параметры man] [раздел] термин ...
       man -f [whatis параметры] страница ...
       man -l [параметры man] файл ...
       man -w|-W [параметры man] страница ...

ОПИСАНИЕ
       man  —  это  пейджер  справочных  страниц  системы. Каждый параметр страница,
       переданный man, обычно является названием программы, утилиты или функции.  По
       каждому  из  этих  параметров  выполняется  поиск  и  вывод  связанной  с ним
       справочной страницы. Если указан  параметр  раздел,  то  это  заставляет  man
       выполнять  поиск  только  в  этом  справочном разделе. Действием по умолчанию
       является поиск во всех доступных  разделах  в  заранее  определённом  порядке
       (смотрите  DEFAULTS)  и  показ  только  первой  найденной страницы, даже если
       существуют страницы в нескольких разделах.

       В таблице ниже показаны номера справочных разделов и описание их содержимого.

       1   Исполняемые программы или команды оболочки (shell)
       2   Системные вызовы (функции, предоставляемые ядром)
       3   Библиотечные вызовы (функции, предоставляемые программными библиотеками)
       4   Специальные файлы (обычно находящиеся в каталоге /dev)
       5   Форматы файлов и соглашения, например о /etc/passwd
       6   Игры
       7   Разное  (включает  пакеты  макросов  и  соглашения),   например   man(7),
           groff(7), man-pages(7)
       8   Команды    администрирования    системы   (обычно,   запускаемые   только
           суперпользователем)
       9   Процедуры ядра [нестандартный раздел]

       Справочная страница состоит из нескольких разделов.

       Стандартные имена разделов: НАЗВАНИЕ (NAME), СИНТАКСИС (SYNOPSIS),  НАСТРОЙКИ
       (CONFIGURATION),  ОПИСАНИЕ  (DESCRIPTION),  ПАРАМЕТРЫ  (OPTIONS),  КОД ВЫХОДА
       (EXIT STATUS),   ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ   (RETURN VALUE),   ОШИБКИ   (ERRORS),
       ОКРУЖЕНИЕ   (ENVIRONMENT),   ФАЙЛЫ   (FILES),  ВЕРСИИ  (VERSIONS),  СТАНДАРТЫ
       (STANDARDS), ЗАМЕЧАНИЯ  (NOTES),  ОШИБКИ  (BUGS),  ПРИМЕР  (EXAMPLE),  АВТОРЫ
       (AUTHORS) и СМОТРИТЕ ТАКЖЕ (SEE ALSO).

       В  разделе  СИНТАКСИС  используются следующие соглашения (которые также могут
       быть использованы в качестве основы для других разделов).

Вы можете прокручивать man‑страницу с помощью стрелок на клавиатуре и клавиш PgUp/PgDn. Когда закончите чтение, нажмите q, чтобы выйти.

Man‑страницы хранятся в централизованной базе. Если Вам любопытно, эта база располагается в каталоге /usr/share/man, однако взаимодействовать с ней напрямую нет необходимости: Вы просто обращаетесь к ней через команду man.

Аргументы для команды man — это не пути к файлам, а именно имена нужных записей (например, Вы запускаете man yes, чтобы открыть man‑страницу yes, а не man /usr/bin/yes, хотя это и есть реальный путь к программе yes, но такой вызов заставит man отобразить бессмысленный вывод).

В этом задании у программы‑run есть секретная опция, использование которой заставит её вывести флаг. Вам необходимо узнать эту опцию из man‑страницы для run. Желаем удачи!

Документация описывающая принцип работы программы может быть достаточно объемной. Вот несколько полезных советов в навигации:

• Вы можете прокручивать man‑страницы с помощью стрелок (а также клавиш PgUp/PgDn) и выполнять поиск по символу /.
• После запуска поиска можно нажимать n, чтобы переходить к следующему результату, и N, чтобы вернуться к предыдущему.
• Вместо / можно использовать ?, чтобы искать в обратном направлении!

Найдите опцию, которая выдаст Вам флаг, прочитав man‑страницу для /challenge/run.

Зачастую самой сложной частью задачи является нахождение нужного справочного фаайла, а не чтение самого мануала. В текущем испытании Вам требуется развить свои навыки поиска нужной документации.

Этот хитрое испытание: скрипт запуска скрывает man‑страницу для программы‑задания, случайным образом изменяя её имя. К счастью, все man‑страницы собраны в единой поисковой базе, поэтому Вы можете выполнить поиск по этой базе, чтобы найти спрятанную man‑страницу для /challenge/run.

Чтобы разобраться, как искать нужную man‑страницу, прочитайте man‑страницу самой команды man, выполнив: man man!

СОВЕТ:
man man объясняет расширенный способ использования самой команды man, и Вам нужно воспользоваться этими знаниями, чтобы понять, как найти скрытую man‑страницу, в которой описано, как пользоваться /challenge/run.

ПОДСКАЗКА:
Хотя имя man‑страницы выбирается случайно, для получения флага Вы всё так же используете /challenge/run!

Некоторые программы не имеют man‑страницы, но могут подсказать, как их запускать, если вызвать их со специальным аргументом. Обычно таким аргументом является --help, но нередко используется и -h, а в редких случаях — -?, help или другие необычные варианты вроде /?.

ПРИМЕЧАНИЕ:
-? и /? чаще встречается в Windows, но некоторые партированные (перенесенные из другой ОС) команды могут использовать их и в Linux.

В этом уровне Вы потренируетесь читать «встроенную» документацию программы с помощью аргумента --help. Попробуйте запустить /challenge/run корректно!

Некоторые команды, вместо того чтобы быть отдельными программами с man‑страницами и(или) опцией --help, встроены прямо в сам интерпретатор командной строки (shell). Такие команды называются встроенными (builtins).

Вот основные отличия от обычных программ:

• Скорость: Оболочке не нужно искать файл на диске и создавать новый процесс для его запуска. Команда выполняется мгновенно внутри самой оболочки.
• Управление окружением: Только встроенные команды могут менять состояние самой оболочки. Например, команда cd обязана быть встроенной, иначе она изменила бы директорию в отдельном процессе, а не в вашей текущей сессии.
• Виртуальный вызов: В отличие от программ вроде ls или grep, которые лежат в директории на диске, у builtins нет физического пути в файловой системе.

Получить список встроенных команд оболочки можно, выполнив встроенную команду help следующим образом:

hacker@man:~$ help

Чтобы получить справку по конкретной встроенной команде, её имя нужно передать встроенной help. Рассмотрим в качестве примера встроенную команду, с которой Вы уже сталкивались ранее, — cd:

hacker@man:~$ help cd
cd: cd [-L|[-P [-e]] [-@]] [dir]
    Change the shell working directory.
    
    Change the current directory to DIR.  The default DIR is the value of the
    HOME shell variable.
...

В данном задании мы попрактикуемся в использовании help для получения справки по встроенным командам. Команда run, используемая в этом уровне, является встроенной командой оболочки, а не внешней программой. Как и раньше, Вам необходимо обратиться к её справке, чтобы узнать секретное значение, которое нужно ей передать!