20.8. Регистрация ошибок и протоколирование работы сервера #
20.8.1. Куда протоколировать #
log_destination
(string
) #PostgreSQL поддерживает несколько методов протоколирования сообщений сервера: stderr, csvlog, jsonlog и syslog. В Windows также поддерживается eventlog. В качестве значения
log_destination
указывается один или несколько методов протоколирования, разделённых запятыми. По умолчанию используется stderr. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера.Если в
log_destination
включено значение csvlog, то протоколирование ведётся в формате CSV (разделённые запятыми значения). Это удобно для программной обработки журнала. Подробнее об этом в Подразделе 20.8.4. Для вывода в формате CSV должен быть включён logging_collector.Если в
log_destination
включено значение jsonlog, то протоколирование ведётся в формате JSON. Это удобно для программной обработки журнала. Подробнее об этом в Подразделе 20.8.5. Для вывода в формате JSON должен быть включён logging_collector.Если присутствует указание stderr, csvlog или jsonlog, создаётся файл
current_logfiles
, в который записывается расположение файлов журнала, в настоящее время используемых сборщиком сообщений для соответствующих назначений. Это позволяет легко определить, какие файлы журнала используются в данный момент экземпляром сервера. Например, он может иметь такое содержание:stderr log/postgresql.log csvlog log/postgresql.csv jsonlog log/postgresql.json
current_logfiles
переписывается, когда при прокрутке создаётся новый файл журнала или когда изменяется значениеlog_destination
. Он удаляется, когда вlog_destination
не задаётся ни stderr, ни csvlog, ни jsonlog, а также когда сборщик сообщений отключён.Примечание
В большинстве систем Unix потребуется изменить конфигурацию системного демона syslog для использования варианта syslog в
log_destination
. Для указания типа протоколируемой программы (facility), PostgreSQL может использовать значения сLOCAL0
поLOCAL7
(см. syslog_facility). Однако на большинстве платформ конфигурация syslog по умолчанию не учитывает сообщения подобного типа. Чтобы это работало, потребуется добавить в конфигурацию демона syslog что-то подобное:local0.* /var/log/postgresql
Для использования
eventlog
вlog_destination
на Windows, необходимо зарегистрировать источник событий и его библиотеку в операционной системе. Тогда Windows Event Viewer сможет отображать сообщения журнала событий. Подробнее в Разделе 19.12.logging_collector
(boolean
) #Параметр включает сборщик сообщений (logging collector). Это фоновый процесс, который собирает отправленные в stderr сообщения и перенаправляет их в журнальные файлы. Такой подход зачастую более полезен чем запись в syslog, поскольку некоторые сообщения в syslog могут не попасть. (Типичный пример с сообщениями об ошибках динамического связывания, другой пример — ошибки в скриптах типа
archive_command
.) Для установки параметра требуется перезапуск сервера.Примечание
Можно обойтись без сборщика сообщений и просто писать в stderr. Сообщения будут записываться в место, куда направлен поток stderr. Такой способ подойдёт только для небольших объёмов протоколирования, потому что не предоставляет удобных средств для организации ротации журнальных файлов. Кроме того, на некоторых платформах отказ от использования сборщика сообщений может привести к потере или искажению сообщений, так как несколько процессов, одновременно пишущих в один журнальный файл, могут перезаписывать информацию друг друга.
Примечание
Сборщик спроектирован так, чтобы сообщения никогда не терялись. А это значит, что при очень высокой нагрузке, серверные процессы могут быть заблокированы при попытке отправить сообщения во время сбоя фонового процесса сборщика. В противоположность этому, syslog предпочитает удалять сообщения, при невозможности их записать. Поэтому часть сообщений может быть потеряна, но система не будет блокироваться.
log_directory
(string
) #При включённом
logging_collector
, определяет каталог, в котором создаются журнальные файлы. Можно задавать как абсолютный путь, так и относительный от каталога данных кластера. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера. Значение по умолчанию —log
.log_filename
(string
) #При включённом
logging_collector
задаёт имена журнальных файлов. Значение трактуется как строка формата в функцииstrftime
, поэтому в ней можно использовать спецификаторы%
для включения в имена файлов информации о дате и времени. (При наличии зависящих от часового пояса спецификаторов%
будет использован пояс, заданный в log_timezone.) Поддерживаемые спецификаторы%
похожи на те, что перечислены в описании strftime спецификации Open Group. Обратите внимание, что системная функцияstrftime
напрямую не используется. Поэтому нестандартные, специфичные для платформы особенности не будут работать. Значение по умолчаниюpostgresql-%Y-%m-%d_%H%M%S.log
.Если для задания имени файлов не используются спецификаторы
%
, то для избежания переполнения диска, следует использовать утилиты для ротации журнальных файлов. В версиях до 8.4, при отсутствии спецификаторов%
, PostgreSQL автоматически добавлял время в формате Epoch к имени файла. Сейчас в этом больше нет необходимости.Если в
log_destination
включён вывод в формате CSV, то к имени журнального файла будет добавлено расширение.csv
. (Еслиlog_filename
заканчивается на.log
, то это расширение заменится на.csv
.)Если в
log_destination
включён вывод в формате JSON, то к имени журнального файла будет добавлено расширение.json
. (Еслиlog_filename
заканчивается на.log
, то это расширение заменится на.json
.)Задать этот параметр можно только в
postgresql.conf
или в командной строке при запуске сервера.log_file_mode
(integer
) #В системах Unix задаёт права доступа к журнальным файлам, при включённом
logging_collector
. (В Windows этот параметр игнорируется.) Значение параметра должно быть числовым, в формате командchmod
иumask
. (Для восьмеричного формата, требуется задать лидирующий0
(ноль).)Права доступа по умолчанию
0600
, т. е. только владелец сервера может читать и писать в журнальные файлы. Также, может быть полезным значение0640
, разрешающее чтение файлов членам группы. Однако чтобы установить такое значение, нужно каталог для хранения журнальных файлов (log_directory) вынести за пределы каталога данных кластера. В любом случае нежелательно открывать для всех доступ на чтение журнальных файлов, так как они могут содержать конфиденциальные данные.Задать этот параметр можно только в
postgresql.conf
или в командной строке при запуске сервера.log_rotation_age
(integer
) #При включённом
logging_collector
этот параметр определяет максимальное время жизни отдельного журнального файла, по истечении которого создаётся новый файл. Если это значение задаётся без единиц измерения, оно считается заданным в минутах. Значение по умолчанию — 24 часа. При нулевом значении смена файлов по времени не производится. Задать этот параметр можно только вpostgresql.conf
или в командной строке при запуске сервера.log_rotation_size
(integer
) #При включённом
logging_collector
этот параметр определяет максимальный размер отдельного журнального файла. При достижении этого размера создаётся новый файл. Если это значение задаётся без единиц измерения, оно считается заданным в килобайтах. Значение по умолчанию — 10 мегабайт. При нулевом значении смена файлов по размеру не производится. Задать этот параметр можно только вpostgresql.conf
или в командной строке при запуске сервера.log_truncate_on_rotation
(boolean
) #Если параметр
logging_collector
включён, PostgreSQL будет перезаписывать существующие журнальные файлы, а не дописывать в них. Однако перезапись при переключении на новый файл возможна только в результате ротации по времени, но не при старте сервера или ротации по размеру файла. При выключенном параметре всегда продолжается запись в существующий файл. Например, включение этого параметра в комбинации сlog_filename
равнымpostgresql-%H.log
, приведёт к генерации 24-х часовых журнальных файлов, которые циклически перезаписываются. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера.Пример: для хранения журнальных файлов в течение 7 дней, по одному файлу на каждый день с именами вида
server_log.Mon
,server_log.Tue
и т. д., а также с автоматической перезаписью файлов прошлой недели, нужно установитьlog_filename
вserver_log.%a
,log_truncate_on_rotation
вon
иlog_rotation_age
в1440
.Пример: для хранения журнальных файлов в течение 24 часов, по одному файлу на час, с дополнительной возможностью переключения файла при превышения 1ГБ, установите
log_filename
вserver_log.%H%M
,log_truncate_on_rotation
вon
,log_rotation_age
в60
иlog_rotation_size
в1000000
. Добавление%M
вlog_filename
позволит при переключении по размеру указать другое имя файла в пределах одного часа.syslog_facility
(enum
) #При включённом протоколировании в syslog, этот параметр определяет значение «facility». Допустимые значения
LOCAL0
,LOCAL1
,LOCAL2
,LOCAL3
,LOCAL4
,LOCAL5
,LOCAL6
,LOCAL7
. По умолчанию используетсяLOCAL0
. Подробнее в документации на системный демон syslog. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера.syslog_ident
(string
) #При включённом протоколировании в syslog, этот параметр задаёт имя программы, которое будет использоваться в syslog для идентификации сообщений относящихся к PostgreSQL. По умолчанию используется
postgres
. Задать этот параметр можно только вpostgresql.conf
или в командной строке при запуске сервера.syslog_sequence_numbers
(boolean
) #Когда сообщения выводятся в syslog и этот параметр включён (по умолчанию), все сообщения будут предваряться последовательно увеличивающимися номерами (например,
[2]
). Это позволяет обойти подавление повторов «--- последнее сообщение повторилось N раз ---», которое по умолчанию осуществляется во многих реализациях syslog. В более современных реализациях syslog подавление повторных сообщений можно настроить (например, в rsyslog есть директива$RepeatedMsgReduction
), так что это может излишне. Если же вы действительно хотите, чтобы повторные сообщения подавлялись, вы можете отключить этот параметр.Задать этот параметр можно только в
postgresql.conf
или в командной строке при запуске сервера.syslog_split_messages
(boolean
) #Когда активен вывод сообщений в syslog, этот параметр определяет, как будут доставляться сообщения. Если он включён (по умолчанию), сообщения разделяются по строкам, а длинные строки разбиваются на строки не длиннее 1024 байт, что составляет типичное ограничение размера для традиционных реализаций syslog. Когда он отключён, сообщения сервера PostgreSQL передаются службе syslog как есть, и она должна сама корректно воспринять потенциально длинные сообщения.
Если syslog в итоге выводит сообщения в текстовый файл, результат будет тем же и лучше оставить этот параметр включённым, так как многие реализации syslog не способны обрабатывать большие сообщения или их нужно специально настраивать для этого. Но если syslog направляет сообщения в некоторую другую среду, может потребоваться или будет удобнее сохранять логическую целостность сообщений.
Задать этот параметр можно только в
postgresql.conf
или в командной строке при запуске сервера.event_source
(string
) #При включённом протоколировании в event log, этот параметр задаёт имя программы, которое будет использоваться в журнале событий для идентификации сообщений относящихся к PostgreSQL. По умолчанию используется
PostgreSQL
. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера.
20.8.2. Когда протоколировать #
log_min_messages
(enum
) #Управляет минимальным уровнем сообщений, записываемых в журнал сервера. Допустимые значения
DEBUG5
,DEBUG4
,DEBUG3
,DEBUG2
,DEBUG1
,INFO
,NOTICE
,WARNING
,ERROR
,LOG
,FATAL
иPANIC
. Каждый из перечисленных уровней включает все идущие после него. Чем дальше в этом списке уровень сообщения, тем меньше сообщений будет записано в журнал сервера. По умолчанию используетсяWARNING
. Обратите внимание, позицияLOG
здесь отличается от принятой в client_min_messages. Только суперпользователи и пользователи с соответствующим правомSET
могут изменить этот параметр.log_min_error_statement
(enum
) #Управляет тем, какие SQL-операторы, завершившиеся ошибкой, записываются в журнал сервера. SQL-оператор будет записан в журнал, если он завершится ошибкой с указанным уровнем важности или выше. Допустимые значения:
DEBUG5
,DEBUG4
,DEBUG3
,DEBUG2
,DEBUG1
,INFO
,NOTICE
,WARNING
,ERROR
,LOG
,FATAL
иPANIC
. По умолчанию используетсяERROR
. Это означает, что в журнал сервера будут записаны все операторы, завершившиеся сообщением с уровнем важностиERROR
,LOG
,FATAL
иPANIC
. Чтобы фактически отключить запись операторов с ошибками, установите для этого параметра значениеPANIC
. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET
.log_min_duration_statement
(integer
) #Записывает в журнал продолжительность выполнения всех команд, время работы которых не меньше указанного. Например, при значении
250ms
в журнал сервера будут записаны все команды, выполняющиеся 250 миллисекунд и дольше. С помощью этого параметра можно выявить неоптимизированные запросы в приложениях. Если значение этого параметра задаётся без единиц измерения, оно считается заданным в миллисекундах. При нулевом значении записывается продолжительность выполнения всех команд. Со значением -1 (по умолчанию) запись полностью отключается. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET
.Этот параметр переопределяет log_min_duration_sample, то есть запросы с длительностью, превышающей заданное значение, всегда фиксируются в журнале, вне зависимости от параметров извлечения выборки.
Для клиентов, использующих расширенный протокол запросов, будет записываться продолжительность фаз: разбор, связывание и выполнение.
Примечание
При использовании совместно с log_statement, текст SQL-операторов будет записываться только один раз (от использования
log_statement
) и не будет задублирован в сообщении о длительности выполнения. Если не используется вывод в syslog, то рекомендуется в log_line_prefix включить идентификатор процесса или сеанса. Это позволит связать текст запроса с записью о продолжительности выполнения, которая появится позже.log_min_duration_sample
(integer
) #Позволяет сделать выборку по продолжительности команд, которые выполнялись не менее чем определённое время. При этом в журнал будут вноситься такие же записи, как и при включённом параметре log_min_duration_statement, но не для всех команд, а только для их подмножества, ограничиваемого параметром log_statement_sample_rate. Например, при значении
100ms
предварительно для выборки будут отобраны все SQL-операторы, выполняющиеся 100 миллисекунд и дольше. Этот параметр может быть полезен, когда количество запросов слишком велико, чтобы записывать в журнал их все. Если значение этого параметра задаётся без единиц измерения, оно считается заданным в миллисекундах. При нулевом значении для выборки отбираются команды с любой продолжительностью. Со значением -1 (по умолчанию) формирование выборки по продолжительности полностью отключается. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET
.Этот параметр имеет меньший приоритет, чем
log_min_duration_statement
, то есть команды с длительностью, превышающейlog_min_duration_statement
, будут регистрироваться в журнале всегда, вне зависимости от того, какой будет выборка.Другие замечания, относящиеся к
log_min_duration_statement
, применимы так же и к данному параметру.log_statement_sample_rate
(floating point
) #Определяет, какая доля команд с длительностью, достигшей log_min_duration_sample, будет регистрироваться в журнале. Выборка формируется вероятностным образом, например, со значением
0.5
можно считать, что шанс попадания каждой отдельной команды в выборку равен один к двум. Значение по умолчанию —1.0
, то есть выбираются и регистрируются все команды. Со значением 0 запись команд выборки, в зависимости от их длительности, отключается, так же как и приlog_min_duration_sample
, равном-1
. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET
.log_transaction_sample_rate
(floating point
) #Задаёт долю транзакций, команды из которых будут записываться в журнал дополнительно (помимо команд, записываемых по другим причинам). Этот параметр действует на все транзакции, независимо от длительности команд. Выборка осуществляется вероятностным образом, например, со значением
0.1
можно считать, что каждая транзакция может попасть в журнал с шансом один к десяти. Параметрlog_transaction_sample_rate
может быть полезен для анализа выборки транзакций. Значение по умолчанию —0
, то есть команды из дополнительно выбираемых транзакций не записываются. При значении1
записываются все команды из всех транзакций. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET
.Примечание
С этим параметром, как и со всеми остальными, управляющими журналированием команд, могут быть связаны значительные издержки.
log_startup_progress_interval
(integer
) #Задаёт интервал времени, по истечении которого процесс запуска будет выдавать сообщение о длительной операции, которая всё ещё выполняется; с таким же интервалом будут выдаваться и последующие сообщения об этой операции. Значение по умолчанию — 10 секунд. Значение
0
отключает эту функцию. Если это значение указано без единиц измерения, оно считается заданным в миллисекундах. Этот интервал отсчитывается для каждой операции в отдельности. Задать этот параметр можно только в файлеpostgresql.conf
или в командной строке сервера.Например, при значении по умолчанию, равном 10 сек., если синхронизация каталога данных продолжается 25 секунд, а после этого сброс нежурналируемых отношений выполняется 8 секунд, в журнал будет выдано сообщение об операции синхронизации через 10 секунд после её начала, а затем ещё одно сообщение об этой операции, когда её продолжительность достигнет 20 секунд, а сообщений об операции сброса нежурналируемых отношений в журнале не будет.
В Таблице 20.2 поясняются уровни важности сообщений в PostgreSQL. Также в этой таблице показано, как эти уровни транслируются в системные при использовании syslog или eventlog в Windows.
Таблица 20.2. Уровни важности сообщений
Уровень | Использование | syslog | eventlog |
---|---|---|---|
DEBUG1 .. DEBUG5 | Более детальная информация для разработчиков. Чем больше номер, тем детальнее. | DEBUG | INFORMATION |
INFO | Неявно запрошенная пользователем информация, например вывод команды VACUUM VERBOSE . | INFO | INFORMATION |
NOTICE | Информация, которая может быть полезной пользователям. Например, уведомления об усечении длинных идентификаторов. | NOTICE | INFORMATION |
WARNING | Предупреждения о возможных проблемах. Например, COMMIT вне транзакционного блока. | NOTICE | WARNING |
ERROR | Сообщает об ошибке, из-за которой прервана текущая команда. | WARNING | ERROR |
LOG | Информация, полезная для администраторов. Например, выполнение контрольных точек. | INFO | INFORMATION |
FATAL | Сообщает об ошибке, из-за которой прерван текущий сеанс. | ERR | ERROR |
PANIC | Сообщает об ошибке, из-за которой прерваны все сеансы. | CRIT | ERROR |
20.8.3. Что протоколировать #
Примечание
Выбирая, что будет записываться в протокол, важно учитывать возможные риски безопасности; подробнее об этом говорится в Разделе 25.3.
application_name
(string
) #application_name
— это любая строка длиной не болееNAMEDATALEN
символов (64 символа при стандартной сборке). Обычно устанавливается приложением при подключении к серверу. Значение отображается в представленииpg_stat_activity
и добавляется в журнал сервера, при использовании формата CSV. Для прочих форматов,application_name
можно добавить в журнал через параметр log_line_prefix. Значениеapplication_name
может содержать только печатные ASCII символы. Остальные символы заменяются шестнадцатеричными спецсимволами в стиле C.debug_print_parse
(boolean
)debug_print_rewritten
(boolean
)debug_print_plan
(boolean
) #Эти параметры включают вывод различной отладочной информации. А именно: вывод дерева запроса, дерево запроса после применения правил или плана выполнения запроса, соответственно. Все эти сообщения имеют уровень
LOG
. Поэтому, по умолчанию, они записываются в журнал сервера, но не отправляются клиенту. Отправку клиенту можно настроить через client_min_messages и/или log_min_messages. По умолчанию параметры выключены.debug_pretty_print
(boolean
) #Включает выравнивание сообщений, выводимых
debug_print_parse
,debug_print_rewritten
илиdebug_print_plan
. В результате сообщения легче читать, но они значительно длиннее, чем в формате «compact», который используется при выключенном значении. По умолчанию включён.log_autovacuum_min_duration
(integer
) #Задаёт время выполнения действия автоочистки, при превышении которого информация об этом действии записывается в журнал. При нулевом значении в журнале фиксируются все действия автоочистки. Значение
-1
отключает журналирование действий автоочистки. Если это значение задаётся без единиц измерения, оно считается заданным в миллисекундах. Например, если задать значение250ms
, в журнале будут фиксироваться все операции автоматической очистки и анализа, выполняемые дольше 250 мс. Кроме того, когда этот параметр имеет любое значение, отличное от-1
, в журнал будет записываться сообщение в случае пропуска действия автоочистки из-за конфликтующей блокировки или параллельного удаления отношения. Значение по умолчанию —10min
. Во включённом состоянии этот параметр помогает отслеживать активность автоочистки. Задать этот параметр можно только вpostgresql.conf
или в командной строке при запуске сервера. Однако его можно переопределить для отдельных таблиц, изменив их параметры хранения.log_checkpoints
(boolean
) #Включает протоколирование выполнения контрольных точек и точек перезапуска сервера. При этом записывается некоторая статистическая информация. Например, число записанных буферов и время, затраченное на их запись. Параметр можно задать только в конфигурационных файлах или в командной строке при запуске сервера. По умолчанию включён.
log_connections
(boolean
) #Включает протоколирование всех попыток подключения к серверу, в том числе успешного завершения как аутентификации (если она требуется), так и авторизации клиентов. Изменить его можно только в начале сеанса и сделать это могут только суперпользователи и пользователи с соответствующим правом
SET
. Значение по умолчанию —off
.Примечание
Некоторые программы, например psql, предпринимают две попытки подключения (первая для определения, нужен ли пароль). Поэтому дублирование сообщения «connection received» не обязательно говорит о наличии проблемы.
log_disconnections
(boolean
) #Включает протоколирование завершения сеанса. В журнал выводится примерно та же информация, что и с
log_connections
, плюс длительность сеанса. Изменить этот параметр можно только в начале сеанса и сделать это могут только суперпользователи и пользователи с соответствующим правомSET
. Значение по умолчанию —off
.log_duration
(boolean
) #Записывает продолжительность каждой завершённой команды. По умолчанию выключен. Только суперпользователи и пользователи с соответствующим правом
SET
могут изменить этот параметр.Для клиентов, использующих расширенный протокол запросов, будет записываться продолжительность фаз: разбор, связывание и выполнение.
Примечание
Включение параметра
log_duration
не равнозначно установке нулевого значения для log_min_duration_statement. Разница в том, что при превышении значенияlog_min_duration_statement
в журнал записывается текст запроса, а при включении данного параметра — нет. Таким образом, приlog_duration
=on
и положительном значенииlog_min_duration_statement
в журнал записывается длительность для всех команд, а текст запроса — только для команд с длительностью, превышающей предел. Такое поведение может оказаться полезным при сборе статистики в условиях большой нагрузки.log_error_verbosity
(enum
) #Управляет количеством детальной информации, записываемой в журнал сервера для каждого сообщения. Допустимые значения:
TERSE
,DEFAULT
иVERBOSE
. Каждое последующее значение добавляет больше полей в выводимое сообщение. ДляTERSE
из сообщения об ошибке исключаются поляDETAIL
,HINT
,QUERY
иCONTEXT
. ДляVERBOSE
в сообщение включается код ошибкиSQLSTATE
(см. Приложение A), а также имя файла с исходным кодом, имя функции и номер строки сгенерировавшей ошибку. Только суперпользователи и пользователи с соответствующим правомSET
могут изменить этот параметр.log_hostname
(boolean
) #По умолчанию, сообщения журнала содержат лишь IP-адрес подключившегося клиента. При включении этого параметра, дополнительно будет фиксироваться и имя сервера. Обратите внимание, что в зависимости от применяемого способа разрешения имён, это может отрицательно сказаться на производительности. Задать этот параметр можно только в
postgresql.conf
или в командной строке при запуске сервера.log_line_prefix
(string
) #Строка, в стиле функции
printf
, которая выводится в начале каждой строки журнала сообщений. С символов%
начинаются управляющие последовательности, которые заменяются статусной информацией, описанной ниже. Неизвестные управляющие последовательности игнорируются. Все остальные символы напрямую копируются в выводимую строку. Некоторые управляющие последовательности используются только для пользовательских процессов и будут игнорироваться фоновыми процессами, например основным процессом сервера. Статусная информация может быть выровнена по ширине влево или вправо указанием числа после % и перед кодом последовательности. Отрицательное число дополняет значение пробелами справа до заданной ширины, а положительное число — слева. Выравнивание может быть полезно для улучшения читаемости.Этот параметр можно задать только в
postgresql.conf
или в командной строке при запуске сервера. По умолчанию этот параметр имеет значение'%m [%p] '
, с которым в журнал выводится время и идентификатор процесса (PID).Спецсимвол Назначение Только для пользовательского процесса %a
Имя приложения (application_name) да %u
Имя пользователя да %d
Имя базы данных да %r
Имя удалённого узла или IP-адрес, а также номер порта да %h
Имя удалённого узла или IP-адрес да %b
Тип обслуживающего процесса нет %p
Идентификатор процесса нет %P
Идентификатор ведущего процесса группы, если текущий процесс является исполнителем параллельного запроса нет %t
Штамп времени, без миллисекунд нет %m
Штамп времени, с миллисекундами нет %n
Штамп времени, с миллисекундами (в виде времени Unix) нет %i
Тег команды: тип текущей команды в сеансе да %e
Код ошибки SQLSTATE нет %c
Идентификатор сеанса. Подробности ниже нет %l
Номер строки журнала для каждого сеанса или процесса. Начинается с 1 нет %s
Штамп времени начала процесса нет %v
Идентификатор виртуальной транзакции (backendID/localXID); см. Раздел 74.1 нет %x
Идентификатор транзакции (0 если не присвоен); см. Раздел 74.1 нет %q
Ничего не выводит. Непользовательские процессы останавливаются в этой точке. Игнорируется пользовательскими процессами нет %Q
Идентификатор текущего запроса. Вычисление идентификаторов запроса по умолчанию отключено, поэтому в этом поле будет выводиться значение 0, если не включён параметр compute_query_id или не настроен дополнительный модуль, вычисляющий идентификаторы запросов. да %%
Выводит %
нет Тип обслуживающего процесса соответствует содержимому столбца
backend_type
в представленииpg_stat_activity
, но в журнале могут фигурировать и другие типы, которые не показываются в этом представлении.Спецпоследовательность
%c
заменяется на практически уникальный идентификатор сеанса, содержащий из 4 шестнадцатеричных чисел (без ведущих нулей), разделённых точками. Эти числа представляют время запуска процесса и его PID, так что%c
можно использовать как более компактную альтернативу совокупности этих двух элементов. Чтобы получить такой идентификатор сеанса, например изpg_stat_activity
, воспользуйтесь этим запросом:SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' || to_hex(pid) FROM pg_stat_activity;
Подсказка
Последним символом в
log_line_prefix
лучше оставлять пробел, чтобы отделить от остальной строки. Можно использовать и символы пунктуации.Подсказка
Syslog также формирует штамп времени и идентификатор процесса, поэтому вероятно нет смысла использовать соответствующие управляющие последовательности при использовании syslog.
Подсказка
Спецпоследовательность
%q
полезна для включения информации, которая существует только в контексте сеанса (обслуживающего процесса), например, имя пользователя или базы данных. Например:log_line_prefix = '%m [%p] %q%u@%d/%a '
Примечание
Спецпоследовательность
%Q
всегда выдаёт нулевой идентификатор для строк, выводимых посредством log_statement, потому что соответствующий выводlog_statement
формируется до вычисления этого идентификатора, в том числе и для некорректных операторов, для которых идентификатор вычислить нельзя.log_lock_waits
(boolean
) #Определяет, нужно ли фиксировать в журнале события, когда сеанс ожидает получения блокировки дольше, чем указано в deadlock_timeout. Это позволяет выяснить, не связана ли низкая производительность с ожиданием блокировок. По умолчанию отключён. Только суперпользователи и пользователи с соответствующим правом
SET
могут изменить этот параметр.log_recovery_conflict_waits
(boolean
) #Определяет, нужно ли фиксировать в журнале события, когда сеанс ожидает получения блокировки дольше, чем указано в
deadlock_timeout
для конфликтов восстановления. Это позволяет выяснить, препятствуют ли конфликты восстановления применению WAL.Значение по умолчанию —
off
(выкл.). Задать этот параметр можно только вpostgresql.conf
или в командной строке при запуске сервера.log_parameter_max_length
(integer
) #Положительное значение устанавливает количество байт, до которого будут усекаться значения привязанных SQL-параметров, выводимые в сообщениях вместе с SQL-операторами (это не относится к регистрации ошибок). Ноль отключает вывод значений привязанных параметров в таких сообщениях. Значение
-1
(по умолчанию) позволяет получить в журнале привязанные параметры в полном объёме. Если значение этого параметра задаётся без единиц измерения, оно считается заданным в байтах. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET
.Этот параметр влияет только на сообщения, выводимые в журнал по критериям, которые устанавливают параметры log_statement, log_duration и связанные с ними. С ненулевыми значениями этого параметра сопряжены некоторые издержки, особенно если привязанные значения передаются в двоичной форме, так как их нужно будет переводить в текстовый вид.
log_parameter_max_length_on_error
(integer
) #Положительное значение устанавливает количество байт, до которого будут усекаться значения привязанных SQL-параметров, выводимые вместе с SQL-операторами при регистрации ошибок. Нулевое значение отключает вывод значений привязанных операторов в сообщениях об ошибках. Значение
-1
(по умолчанию) позволяет получить в журнале привязанные параметры в полном объёме. Если значение этого параметра задаётся без единиц измерения, оно считается заданным в байтах.С ненулевыми значениями этого параметра сопряжены некоторые издержки, так как PostgreSQL должен будет сформировать в памяти текстовые представления всех значений параметров перед выполнением всех операторов, в том числе, выполненных в итоге без ошибок. Издержки дополнительно возрастают, когда привязанные параметры передаются не в текстовой, а в двоичной форме, так как их недостаточно просто скопировать в строку, их нужно ещё преобразовать.
log_statement
(enum
) #Управляет тем, какие SQL-команды записывать в журнал. Допустимые значения:
none
(отключено),ddl
,mod
иall
(все команды).ddl
записывает все команды определения данных, такие какCREATE
,ALTER
,DROP
.mod
записывает все командыddl
, а также команды изменяющие данные, такие какINSERT
,UPDATE
,DELETE
,TRUNCATE
иCOPY FROM
.PREPARE
,EXECUTE
иEXPLAIN ANALYZE
также записываются, если вызваны для команды соответствующего типа. Если клиент использует расширенный протокол запросов, то запись происходит на фазе выполнения и содержит значения всех связанных переменных (если есть символы одиночных кавычек, то они дублируются).По умолчанию
none
. Только суперпользователи и пользователи с соответствующим правомSET
могут изменить этот параметр.Примечание
Команды с синтаксическими ошибками не записываются, даже если
log_statement
=all
, так как сообщение формируется только после выполнения предварительного разбора, определяющего тип команды. При расширенном протоколе запросов, похожим образом не будут записываться команды, неуспешно завершившиеся до фазы выполнения (например, при разборе или построении плана запроса). Для включения в журнал таких команд установитеlog_min_error_statement
вERROR
(или ниже).Записываемые в журнал команды могут раскрывать конфиденциальные данные и даже содержать незашифрованные пароли.
log_replication_commands
(boolean
) #Включает запись в журнал сервера всех команд репликации. Подробнее о командах репликации можно узнать в Разделе 55.4. Значение по умолчанию —
off
. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET
.log_temp_files
(integer
) #Управляет регистрацией в журнале имён и размеров временных файлов. Временные файлы могут использоваться для сортировки, хеширования и временного хранения результатов запросов. Когда этот параметр включён, при удалении временного файла информация о нём может записываться в журнал с указанием размера файла в байтах. При нулевом значении записывается информация обо всех файлах, а при положительном — о файлах, размер которых не меньше заданной величины. Если это значение задаётся без единиц измерения, оно считается заданным в килобайтах. Значение по умолчанию равно -1, то есть запись такой информации отключена. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правом
SET
.log_timezone
(string
) #Устанавливает часовой пояс для штампов времени при записи в журнал сервера. В отличие от TimeZone, это значение одинаково для всех баз данных кластера, поэтому для всех сеансов используются согласованные значения штампов времени. Встроенное значение по умолчанию
GMT
, но оно переопределяется вpostgresql.conf
: initdb записывает в него значение, соответствующее системной среде. Подробнее об этом в Подразделе 8.5.3. Задать этот параметр можно только вpostgresql.conf
или в командной строке при запуске сервера.
20.8.4. Использование вывода журнала в формате CSV #
Добавление csvlog
в log_destination
делает удобным загрузку журнальных файлов в таблицу базы данных. Строки журнала представляют собой значения, разделённые запятыми (формат CSV), со следующими полями: штамп времени с миллисекундами; имя пользователя; имя базы данных; идентификатор процесса; клиентский узел:номер порта; идентификатор сеанса; номер строки каждого сеанса; тег команды; время начала сеанса; виртуальный идентификатор транзакции; идентификатор транзакции; уровень важности ошибки; код ошибки SQLSTATE; сообщение об ошибке; подробности к сообщению об ошибке; подсказка к сообщению об ошибке; внутренний запрос, приведший к ошибке (если есть); номер символа внутреннего запроса, где произошла ошибка; контекст ошибки; запрос пользователя, приведший к ошибке (если есть и включён log_min_error_statement
); номер символа в запросе пользователя, где произошла ошибка; расположение ошибки в исходном коде PostgreSQL (если log_error_verbosity
установлен в verbose
), имя приложения, тип обслуживающего процесса, идентификатор ведущего процесса группы и идентификатор запроса. Вот пример определения таблицы, для хранения журналов в формате CSV:
CREATE TABLE postgres_log ( log_time timestamp(3) with time zone, user_name text, database_name text, process_id integer, connection_from text, session_id text, session_line_num bigint, command_tag text, session_start_time timestamp with time zone, virtual_transaction_id text, transaction_id bigint, error_severity text, sql_state_code text, message text, detail text, hint text, internal_query text, internal_query_pos integer, context text, query text, query_pos integer, location text, application_name text, backend_type text, leader_pid integer, query_id bigint, PRIMARY KEY (session_id, session_line_num) );
Для загрузки журнального файла в такую таблицу можно использовать команду COPY FROM
:
COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
Также можно обратиться к этому файлу как к сторонней таблице, используя поставляемый модуль file_fdw.
Для упрощения загрузки журналов в CSV формате используйте следующее:
Установите для
log_filename
иlog_rotation_age
значения, гарантирующие согласованную и предсказуемую схему именования журнальных файлов. Зная, какие имена будут у журнальных файлов, можно определить, когда конкретный файл заполнен и готов к загрузке.Установите
log_rotation_size
в 0, чтобы запретить ротацию файлов по достижении определённого размера, так как это делает непредсказуемой схему именования журнальных файлов.Установите
log_truncate_on_rotation
вon
, чтобы новые сообщения не смешивались со старыми при переключении на существующий файл.Определение таблицы содержит первичный ключ. Это полезно для предотвращения случайной повторной загрузки данных. Команда
COPY
фиксирует изменения один раз, поэтому любая ошибка приведёт к отмене всей загрузки. Если сначала загрузить неполный журнальный файл, то его повторная загрузка (по заполнении) приведёт к нарушению первичного ключа и, следовательно, к ошибке загрузки. Поэтому необходимо дожидаться окончания записи в журнальный файл перед началом загрузки. Похожим образом предотвращается случайная загрузка частично сформированной строки сообщения, что также приведёт к сбою в командеCOPY
.
20.8.5. Использование вывода журнала в формате JSON #
Добавление jsonlog
в список log_destination
позволяет легко импортировать файлы журналов в различные программы. Когда выбран этот метод, строки журнала выводятся в формате JSON.
В этом формате строковые поля, содержащие NULL, не выводятся. Описанный ниже набор полей не окончательный, в будущем могут появиться новые поля. При обработке вывода jsonlog
в пользовательских приложениях поля, неизвестные для этих приложений, должны игнорироваться.
Каждая строка журнала сериализуется в виде объекта JSON с набором ключей и связанных с ними значений, перечисленных в Таблица 20.3.
Таблица 20.3. Ключи и значения записей журнала в формате JSON
Имя ключа | Тип | Описание |
---|---|---|
timestamp | строка | Штамп времени, с миллисекундами |
user | строка | Имя пользователя |
dbname | строка | Имя базы данных |
pid | число | Идентификатор процесса |
remote_host | строка | Компьютер клиента |
remote_port | число | Порт клиента |
session_id | строка | Идентификатор сеанса |
line_num | число | Номер строки внутри сеанса |
ps | строка | Текущая строка для ps |
session_start | строка | Время начала сеанса |
vxid | строка | Идентификатор виртуальной транзакции |
txid | строка | Идентификатор обычной транзакции |
error_severity | строка | Уровень ошибки |
state_code | строка | Код SQLSTATE |
message | строка | Сообщение об ошибке |
detail | строка | Подробное сообщение об ошибке |
hint | строка | Подсказка, связанная с ошибкой |
internal_query | строка | Внутренний запрос, вызвавший ошибку |
internal_position | число | Положение курсора в тексте внутреннего запроса |
context | строка | Контекст ошибки |
statement | строка | Строка запроса, предоставленная клиентом |
cursor_position | число | Положение курсора в строке запроса |
func_name | строка | Имя функции, в которой произошла ошибка |
file_name | строка | Имя файла, в котором произошла ошибка |
file_line_num | число | Номер строки в файле, где произошла ошибка |
application_name | строка | Имя клиентского приложения |
backend_type | строка | Тип обслуживающего процесса |
leader_pid | число | Идентификатор ведущего процесса группы параллельных исполнителей |
query_id | число | Идентификатор запроса |
20.8.6. Заголовок процесса #
Эти параметры влияют на то, как формируются заголовки серверных процессов. Заголовок процесса обычно можно наблюдать в программах типа ps, а в Windows — в Process Explorer. За подробностями обратитесь к Разделу 28.1.
cluster_name
(string
) #Задаёт имя, которое идентифицирует данный кластер (экземпляр сервера) для различных целей. Имя кластера выводится в заголовке процесса для всех серверных процессов в данном кластере. Более того, это имя будет именем приложения по умолчанию, используемым при подключении ведомого сервера (см. synchronous_standby_names).
Это имя может быть любой строкой не длиннее
NAMEDATALEN
символов (64 символа в стандартной сборке). В строкеcluster_name
могут использоваться только печатаемые ASCII-символы. Остальные символы заменяются шестнадцатеричными спецсимволами в стиле C. Если этот параметр содержит пустую строку''
(это значение по умолчанию), никакое имя не выводится. Этот параметр можно задать только при запуске сервера.update_process_title
(boolean
) #Включает изменение заголовка процесса при получении сервером каждой очередной команды SQL. На большинстве платформ он включён (имеет значение
on
), но в Windows по умолчанию выключен (off
) ввиду больших издержек на изменение этого заголовка. Изменить этот параметр могут только суперпользователи и пользователи с соответствующим правомSET
.
18.3. Connections and Authentication #
18.3.1. Connection Settings #
listen_addresses
(string
) #Specifies the TCP/IP address(es) on which the server is to listen for connections from client applications. The value takes the form of a comma-separated list of host names and/or numeric IP addresses. The special entry
*
corresponds to all available IP interfaces. The entry0.0.0.0
allows listening for all IPv4 addresses and::
allows listening for all IPv6 addresses. If the list is empty, the server does not listen on any IP interface at all, in which case only Unix-domain sockets can be used to connect to it. If the list is not empty, the server will start if it can listen on at least one TCP/IP address. A warning will be emitted for any TCP/IP address which cannot be opened. The default value is localhost, which allows only local TCP/IP “loopback” connections to be made.While client authentication (Chapter 19) allows fine-grained control over who can access the server,
listen_addresses
controls which interfaces accept connection attempts, which can help prevent repeated malicious connection requests on insecure network interfaces. This parameter can only be set at server start.port
(integer
) #The TCP port the server listens on; 5432 by default. Note that the same port number is used for all IP addresses the server listens on. This parameter can only be set at server start.
max_connections
(integer
) #Determines the maximum number of concurrent connections to the database server. The default is typically 100 connections, but might be less if your kernel settings will not support it (as determined during initdb). This parameter can only be set at server start.
Postgres Pro sizes certain resources based directly on the value of
max_connections
. Increasing its value leads to higher allocation of those resources, including shared memory.When running a standby server, you must set this parameter to the same or higher value than on the primary server. Otherwise, queries will not be allowed in the standby server.
reserved_connections
(integer
) #Determines the number of connection “slots” that are reserved for connections by roles with privileges of the
pg_use_reserved_connections
role. Whenever the number of free connection slots is greater than superuser_reserved_connections but less than or equal to the sum ofsuperuser_reserved_connections
andreserved_connections
, new connections will be accepted only for superusers and roles with privileges ofpg_use_reserved_connections
. Ifsuperuser_reserved_connections
or fewer connection slots are available, new connections will be accepted only for superusers.The default value is zero connections. The value must be less than
max_connections
minussuperuser_reserved_connections
. This parameter can only be set at server start.superuser_reserved_connections
(integer
) #Determines the number of connection “slots” that are reserved for connections by Postgres Pro superusers. At most max_connections connections can ever be active simultaneously. Whenever the number of active concurrent connections is at least
max_connections
minussuperuser_reserved_connections
, new connections will be accepted only for superusers. The connection slots reserved by this parameter are intended as final reserve for emergency use after the slots reserved by reserved_connections have been exhausted.The default value is three connections. The value must be less than
max_connections
minusreserved_connections
. This parameter can only be set at server start.unix_socket_directories
(string
) #Specifies the directory of the Unix-domain socket(s) on which the server is to listen for connections from client applications. Multiple sockets can be created by listing multiple directories separated by commas. Whitespace between entries is ignored; surround a directory name with double quotes if you need to include whitespace or commas in the name. An empty value specifies not listening on any Unix-domain sockets, in which case only TCP/IP sockets can be used to connect to the server.
A value that starts with
@
specifies that a Unix-domain socket in the abstract namespace should be created (currently supported on Linux only). In that case, this value does not specify a “directory” but a prefix from which the actual socket name is computed in the same manner as for the file-system namespace. While the abstract socket name prefix can be chosen freely, since it is not a file-system location, the convention is to nonetheless use file-system-like values such as@/tmp
.The default value is normally
/tmp
, but that can be changed at build time. On Windows, the default is empty, which means no Unix-domain socket is created by default. This parameter can only be set at server start.In addition to the socket file itself, which is named
.s.PGSQL.
wherennnn
nnnn
is the server's port number, an ordinary file named.s.PGSQL.
will be created in each of thennnn
.lockunix_socket_directories
directories. Neither file should ever be removed manually. For sockets in the abstract namespace, no lock file is created.unix_socket_group
(string
) #Sets the owning group of the Unix-domain socket(s). (The owning user of the sockets is always the user that starts the server.) In combination with the parameter
unix_socket_permissions
this can be used as an additional access control mechanism for Unix-domain connections. By default this is the empty string, which uses the default group of the server user. This parameter can only be set at server start.This parameter is not supported on Windows. Any setting will be ignored. Also, sockets in the abstract namespace have no file owner, so this setting is also ignored in that case.
unix_socket_permissions
(integer
) #Sets the access permissions of the Unix-domain socket(s). Unix-domain sockets use the usual Unix file system permission set. The parameter value is expected to be a numeric mode specified in the format accepted by the
chmod
andumask
system calls. (To use the customary octal format the number must start with a0
(zero).)The default permissions are
0777
, meaning anyone can connect. Reasonable alternatives are0770
(only user and group, see alsounix_socket_group
) and0700
(only user). (Note that for a Unix-domain socket, only write permission matters, so there is no point in setting or revoking read or execute permissions.)This access control mechanism is independent of the one described in Chapter 19.
This parameter can only be set at server start.
This parameter is irrelevant on systems, notably Solaris as of Solaris 10, that ignore socket permissions entirely. There, one can achieve a similar effect by pointing
unix_socket_directories
to a directory having search permission limited to the desired audience.Sockets in the abstract namespace have no file permissions, so this setting is also ignored in that case.
bonjour
(boolean
) #Enables advertising the server's existence via Bonjour. The default is off. This parameter can only be set at server start.
bonjour_name
(string
) #Specifies the Bonjour service name. The computer name is used if this parameter is set to the empty string
''
(which is the default). This parameter is ignored if the server was not compiled with Bonjour support. This parameter can only be set at server start.
18.3.2. TCP Settings #
tcp_keepalives_idle
(integer
) #Specifies the amount of time with no network activity after which the operating system should send a TCP keepalive message to the client. If this value is specified without units, it is taken as seconds. A value of 0 (the default) selects the operating system's default. On Windows, setting a value of 0 will set this parameter to 2 hours, since Windows does not provide a way to read the system default value. This parameter is supported only on systems that support
TCP_KEEPIDLE
or an equivalent socket option, and on Windows; on other systems, it must be zero. In sessions connected via a Unix-domain socket, this parameter is ignored and always reads as zero.tcp_keepalives_interval
(integer
) #Specifies the amount of time after which a TCP keepalive message that has not been acknowledged by the client should be retransmitted. If this value is specified without units, it is taken as seconds. A value of 0 (the default) selects the operating system's default. On Windows, setting a value of 0 will set this parameter to 1 second, since Windows does not provide a way to read the system default value. This parameter is supported only on systems that support
TCP_KEEPINTVL
or an equivalent socket option, and on Windows; on other systems, it must be zero. In sessions connected via a Unix-domain socket, this parameter is ignored and always reads as zero.tcp_keepalives_count
(integer
) #Specifies the number of TCP keepalive messages that can be lost before the server's connection to the client is considered dead. A value of 0 (the default) selects the operating system's default. This parameter is supported only on systems that support
TCP_KEEPCNT
or an equivalent socket option (which does not include Windows); on other systems, it must be zero. In sessions connected via a Unix-domain socket, this parameter is ignored and always reads as zero.tcp_user_timeout
(integer
) #Specifies the amount of time that transmitted data may remain unacknowledged before the TCP connection is forcibly closed. If this value is specified without units, it is taken as milliseconds. A value of 0 (the default) selects the operating system's default. This parameter is supported only on systems that support
TCP_USER_TIMEOUT
(which does not include Windows); on other systems, it must be zero. In sessions connected via a Unix-domain socket, this parameter is ignored and always reads as zero.client_connection_check_interval
(integer
) #Sets the time interval between optional checks that the client is still connected, while running queries. The check is performed by polling the socket, and allows long running queries to be aborted sooner if the kernel reports that the connection is closed.
This option relies on kernel events exposed by Linux, macOS, illumos and the BSD family of operating systems, and is not currently available on other systems.
If the value is specified without units, it is taken as milliseconds. The default value is
0
, which disables connection checks. Without connection checks, the server will detect the loss of the connection only at the next interaction with the socket, when it waits for, receives or sends data.For the kernel itself to detect lost TCP connections reliably and within a known timeframe in all scenarios including network failure, it may also be necessary to adjust the TCP keepalive settings of the operating system, or the tcp_keepalives_idle, tcp_keepalives_interval and tcp_keepalives_count settings of Postgres Pro.
18.3.3. Authentication #
authentication_timeout
(integer
) #Maximum amount of time allowed to complete client authentication. If a would-be client has not completed the authentication protocol in this much time, the server closes the connection. This prevents hung clients from occupying a connection indefinitely. If this value is specified without units, it is taken as seconds. The default is one minute (
1m
). This parameter can only be set in thepostgresql.conf
file or on the server command line.password_encryption
(enum
) #When a password is specified in CREATE ROLE or ALTER ROLE, this parameter determines the algorithm to use to encrypt the password. Possible values are
scram-sha-256
, which will encrypt the password with SCRAM-SHA-256, andmd5
, which stores the password as an MD5 hash. The default isscram-sha-256
.Note that older clients might lack support for the SCRAM authentication mechanism, and hence not work with passwords encrypted with SCRAM-SHA-256. See Section 19.5 for more details.
scram_iterations
(integer
) #The number of computational iterations to be performed when encrypting a password using SCRAM-SHA-256. The default is
4096
. A higher number of iterations provides additional protection against brute-force attacks on stored passwords, but makes authentication slower. Changing the value has no effect on existing passwords encrypted with SCRAM-SHA-256 as the iteration count is fixed at the time of encryption. In order to make use of a changed value, a new password must be set.krb_server_keyfile
(string
) #Sets the location of the server's Kerberos key file. The default is
FILE:/usr/local/pgsql/etc/krb5.keytab
(where the directory part is whatever was specified assysconfdir
at build time; usepg_config --sysconfdir
to determine that). If this parameter is set to an empty string, it is ignored and a system-dependent default is used. This parameter can only be set in thepostgresql.conf
file or on the server command line. See Section 19.6 for more information.krb_caseins_users
(boolean
) #Sets whether GSSAPI user names should be treated case-insensitively. The default is
off
(case sensitive). This parameter can only be set in thepostgresql.conf
file or on the server command line.gss_accept_delegation
(boolean
) #Sets whether GSSAPI delegation should be accepted from the client. The default is
off
meaning credentials from the client will not be accepted. Changing this toon
will make the server accept credentials delegated to it from the client. This parameter can only be set in thepostgresql.conf
file or on the server command line.
18.3.4. SSL #
See Section 17.9 for more information about setting up SSL. The configuration parameters for controlling transfer encryption using TLS protocols are named ssl
for historic reasons, even though support for the SSL protocol has been deprecated. SSL is in this context used interchangeably with TLS.
ssl
(boolean
) #Enables SSL connections. This parameter can only be set in the
postgresql.conf
file or on the server command line. The default isoff
.ssl_ca_file
(string
) #Specifies the name of the file containing the SSL server certificate authority (CA). Relative paths are relative to the data directory. This parameter can only be set in the
postgresql.conf
file or on the server command line. The default is empty, meaning no CA file is loaded, and client certificate verification is not performed.ssl_cert_file
(string
) #Specifies the name of the file containing the SSL server certificate. Relative paths are relative to the data directory. This parameter can only be set in the
postgresql.conf
file or on the server command line. The default isserver.crt
.ssl_crl_file
(string
) #Specifies the name of the file containing the SSL client certificate revocation list (CRL). Relative paths are relative to the data directory. This parameter can only be set in the
postgresql.conf
file or on the server command line. The default is empty, meaning no CRL file is loaded (unless ssl_crl_dir is set).ssl_crl_dir
(string
) #Specifies the name of the directory containing the SSL client certificate revocation list (CRL). Relative paths are relative to the data directory. This parameter can only be set in the
postgresql.conf
file or on the server command line. The default is empty, meaning no CRLs are used (unless ssl_crl_file is set).The directory needs to be prepared with the OpenSSL command
openssl rehash
orc_rehash
. See its documentation for details.When using this setting, CRLs in the specified directory are loaded on-demand at connection time. New CRLs can be added to the directory and will be used immediately. This is unlike ssl_crl_file, which causes the CRL in the file to be loaded at server start time or when the configuration is reloaded. Both settings can be used together.
ssl_key_file
(string
) #Specifies the name of the file containing the SSL server private key. Relative paths are relative to the data directory. This parameter can only be set in the
postgresql.conf
file or on the server command line. The default isserver.key
.ssl_ciphers
(string
) #Specifies a list of SSL cipher suites that are allowed to be used by SSL connections. See the ciphers manual page in the OpenSSL package for the syntax of this setting and a list of supported values. Only connections using TLS version 1.2 and lower are affected. There is currently no setting that controls the cipher choices used by TLS version 1.3 connections. The default value is
HIGH:MEDIUM:+3DES:!aNULL
. The default is usually a reasonable choice unless you have specific security requirements.This parameter can only be set in the
postgresql.conf
file or on the server command line.Explanation of the default value:
HIGH
#Cipher suites that use ciphers from
HIGH
group (e.g., AES, Camellia, 3DES)MEDIUM
#Cipher suites that use ciphers from
MEDIUM
group (e.g., RC4, SEED)+3DES
#The OpenSSL default order for
HIGH
is problematic because it orders 3DES higher than AES128. This is wrong because 3DES offers less security than AES128, and it is also much slower.+3DES
reorders it after all otherHIGH
andMEDIUM
ciphers.!aNULL
#Disables anonymous cipher suites that do no authentication. Such cipher suites are vulnerable to MITM attacks and therefore should not be used.
Available cipher suite details will vary across OpenSSL versions. Use the command
openssl ciphers -v 'HIGH:MEDIUM:+3DES:!aNULL'
to see actual details for the currently installed OpenSSL version. Note that this list is filtered at run time based on the server key type.ssl_prefer_server_ciphers
(boolean
) #Specifies whether to use the server's SSL cipher preferences, rather than the client's. This parameter can only be set in the
postgresql.conf
file or on the server command line. The default ison
.Postgres Pro versions before 9.4 do not have this setting and always use the client's preferences. This setting is mainly for backward compatibility with those versions. Using the server's preferences is usually better because it is more likely that the server is appropriately configured.
ssl_ecdh_curve
(string
) #Specifies the name of the curve to use in ECDH key exchange. It needs to be supported by all clients that connect. It does not need to be the same curve used by the server's Elliptic Curve key. This parameter can only be set in the
postgresql.conf
file or on the server command line. The default isprime256v1
.OpenSSL names for the most common curves are:
prime256v1
(NIST P-256),secp384r1
(NIST P-384),secp521r1
(NIST P-521). The full list of available curves can be shown with the commandopenssl ecparam -list_curves
. Not all of them are usable in TLS though.ssl_min_protocol_version
(enum
) #Sets the minimum SSL/TLS protocol version to use. Valid values are currently:
TLSv1
,TLSv1.1
,TLSv1.2
,TLSv1.3
. Older versions of the OpenSSL library do not support all values; an error will be raised if an unsupported setting is chosen. Protocol versions before TLS 1.0, namely SSL version 2 and 3, are always disabled.The default is
TLSv1.2
, which satisfies industry best practices as of this writing.This parameter can only be set in the
postgresql.conf
file or on the server command line.ssl_max_protocol_version
(enum
) #Sets the maximum SSL/TLS protocol version to use. Valid values are as for ssl_min_protocol_version, with addition of an empty string, which allows any protocol version. The default is to allow any version. Setting the maximum protocol version is mainly useful for testing or if some component has issues working with a newer protocol.
This parameter can only be set in the
postgresql.conf
file or on the server command line.ssl_dh_params_file
(string
) #Specifies the name of the file containing Diffie-Hellman parameters used for so-called ephemeral DH family of SSL ciphers. The default is empty, in which case compiled-in default DH parameters used. Using custom DH parameters reduces the exposure if an attacker manages to crack the well-known compiled-in DH parameters. You can create your own DH parameters file with the command
openssl dhparam -out dhparams.pem 2048
.This parameter can only be set in the
postgresql.conf
file or on the server command line.ssl_passphrase_command
(string
) #Sets an external command to be invoked when a passphrase for decrypting an SSL file such as a private key needs to be obtained. By default, this parameter is empty, which means the built-in prompting mechanism is used.
The command must print the passphrase to the standard output and exit with code 0. In the parameter value,
%p
is replaced by a prompt string. (Write%%
for a literal%
.) Note that the prompt string will probably contain whitespace, so be sure to quote adequately. A single newline is stripped from the end of the output if present.The command does not actually have to prompt the user for a passphrase. It can read it from a file, obtain it from a keychain facility, or similar. It is up to the user to make sure the chosen mechanism is adequately secure.
This parameter can only be set in the
postgresql.conf
file or on the server command line.ssl_passphrase_command_supports_reload
(boolean
) #This parameter determines whether the passphrase command set by
ssl_passphrase_command
will also be called during a configuration reload if a key file needs a passphrase. If this parameter is off (the default), thenssl_passphrase_command
will be ignored during a reload and the SSL configuration will not be reloaded if a passphrase is needed. That setting is appropriate for a command that requires a TTY for prompting, which might not be available when the server is running. Setting this parameter to on might be appropriate if the passphrase is obtained from a file, for example.This parameter can only be set in the
postgresql.conf
file or on the server command line.