From c5b7d9c16449f63bcf570772badcb5485cead3f7 Mon Sep 17 00:00:00 2001 From: "Endi S. Dewata" Date: Thu, 17 Nov 2016 00:10:55 +0100 Subject: [PATCH 1/8] Removed unused CA and KRA logging.properties. The logging.properties files in CA and KRA folders are never deployed so they have been removed. https://fedorahosted.org/pki/ticket/1897 (cherry picked from commit f6ee4065c0bdb59e22fa92c5f56d49851f4ec6e1) (cherry picked from commit 038f18ae08e760f96524a73c02f452711601bdb0) --- base/ca/shared/conf/logging.properties | 70 --------------------------------- base/kra/shared/conf/logging.properties | 70 --------------------------------- 2 files changed, 140 deletions(-) delete mode 100644 base/ca/shared/conf/logging.properties delete mode 100644 base/kra/shared/conf/logging.properties diff --git a/base/ca/shared/conf/logging.properties b/base/ca/shared/conf/logging.properties deleted file mode 100644 index 796cfc0..0000000 --- a/base/ca/shared/conf/logging.properties +++ /dev/null @@ -1,70 +0,0 @@ -# --- BEGIN COPYRIGHT BLOCK --- -# Copyright (C) 2006-2010 Red Hat, Inc. -# All rights reserved. -# Modifications: configuration parameters -# --- END COPYRIGHT BLOCK --- - -# 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. - -handlers = 1catalina.org.apache.juli.FileHandler, 2localhost.org.apache.juli.FileHandler, 3manager.org.apache.juli.FileHandler, 4host-manager.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler - -.handlers = 1catalina.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler - -############################################################ -# Handler specific properties. -# Describes specific configuration info for Handlers. -############################################################ - -1catalina.org.apache.juli.FileHandler.level = FINE -1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs -1catalina.org.apache.juli.FileHandler.prefix = catalina. - -2localhost.org.apache.juli.FileHandler.level = FINE -2localhost.org.apache.juli.FileHandler.directory = ${catalina.base}/logs -2localhost.org.apache.juli.FileHandler.prefix = localhost. - -3manager.org.apache.juli.FileHandler.level = FINE -3manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs -3manager.org.apache.juli.FileHandler.prefix = manager. - -4host-manager.org.apache.juli.FileHandler.level = FINE -4host-manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs -4host-manager.org.apache.juli.FileHandler.prefix = host-manager. - -java.util.logging.ConsoleHandler.level = FINE -java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter - - -############################################################ -# Facility specific properties. -# Provides extra control for each logger. -############################################################ - -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = 2localhost.org.apache.juli.FileHandler - -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].level = INFO -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].handlers = 3manager.org.apache.juli.FileHandler - -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager].level = INFO -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager].handlers = 4host-manager.org.apache.juli.FileHandler - -# For example, set the com.xyz.foo logger to only log SEVERE -# messages: -#org.apache.catalina.startup.ContextConfig.level = FINE -#org.apache.catalina.startup.HostConfig.level = FINE -#org.apache.catalina.session.ManagerBase.level = FINE -#org.apache.catalina.core.AprLifecycleListener.level=FINE diff --git a/base/kra/shared/conf/logging.properties b/base/kra/shared/conf/logging.properties deleted file mode 100644 index 796cfc0..0000000 --- a/base/kra/shared/conf/logging.properties +++ /dev/null @@ -1,70 +0,0 @@ -# --- BEGIN COPYRIGHT BLOCK --- -# Copyright (C) 2006-2010 Red Hat, Inc. -# All rights reserved. -# Modifications: configuration parameters -# --- END COPYRIGHT BLOCK --- - -# 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. - -handlers = 1catalina.org.apache.juli.FileHandler, 2localhost.org.apache.juli.FileHandler, 3manager.org.apache.juli.FileHandler, 4host-manager.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler - -.handlers = 1catalina.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler - -############################################################ -# Handler specific properties. -# Describes specific configuration info for Handlers. -############################################################ - -1catalina.org.apache.juli.FileHandler.level = FINE -1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs -1catalina.org.apache.juli.FileHandler.prefix = catalina. - -2localhost.org.apache.juli.FileHandler.level = FINE -2localhost.org.apache.juli.FileHandler.directory = ${catalina.base}/logs -2localhost.org.apache.juli.FileHandler.prefix = localhost. - -3manager.org.apache.juli.FileHandler.level = FINE -3manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs -3manager.org.apache.juli.FileHandler.prefix = manager. - -4host-manager.org.apache.juli.FileHandler.level = FINE -4host-manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs -4host-manager.org.apache.juli.FileHandler.prefix = host-manager. - -java.util.logging.ConsoleHandler.level = FINE -java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter - - -############################################################ -# Facility specific properties. -# Provides extra control for each logger. -############################################################ - -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = 2localhost.org.apache.juli.FileHandler - -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].level = INFO -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/manager].handlers = 3manager.org.apache.juli.FileHandler - -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager].level = INFO -org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/host-manager].handlers = 4host-manager.org.apache.juli.FileHandler - -# For example, set the com.xyz.foo logger to only log SEVERE -# messages: -#org.apache.catalina.startup.ContextConfig.level = FINE -#org.apache.catalina.startup.HostConfig.level = FINE -#org.apache.catalina.session.ManagerBase.level = FINE -#org.apache.catalina.core.AprLifecycleListener.level=FINE -- 1.8.3.1 From b64fa73078df0e750a54fd8ee4fb1581f5be0e97 Mon Sep 17 00:00:00 2001 From: "Endi S. Dewata" Date: Thu, 17 Nov 2016 00:27:58 +0100 Subject: [PATCH 3/8] Updated logging.properties. To reduce maintenance the logging.properties is no longer copied into the instance folder during deployment. Instead, a link will be created in /etc/pki/ pointing to the default file in /usr/share/pki/server/conf. The default logging.properties has been updated to only log messages with level WARNING or higher on the console. https://fedorahosted.org/pki/ticket/1897 (cherry picked from commit e674bc51b4d23bc362a1312addd0b09625cf5747) (cherry picked from commit 882ad281c235cbe3a3074d1da00acb8c1b486d6f) --- base/common/share/etc/logging.properties | 1 + .../deployment/scriptlets/instance_layout.py | 16 +++++++++++++-- base/server/share/conf/logging.properties | 24 +++++----------------- 3 files changed, 20 insertions(+), 21 deletions(-) diff --git a/base/common/share/etc/logging.properties b/base/common/share/etc/logging.properties index bd5b5b6..fe879c4 100644 --- a/base/common/share/etc/logging.properties +++ b/base/common/share/etc/logging.properties @@ -26,3 +26,4 @@ java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter java.util.logging.SimpleFormatter.format = %4$s: %5$s%6$s%n .level = WARNING +.handlers = java.util.logging.ConsoleHandler diff --git a/base/server/python/pki/server/deployment/scriptlets/instance_layout.py b/base/server/python/pki/server/deployment/scriptlets/instance_layout.py index c470c7f..07eecbd 100644 --- a/base/server/python/pki/server/deployment/scriptlets/instance_layout.py +++ b/base/server/python/pki/server/deployment/scriptlets/instance_layout.py @@ -55,6 +55,13 @@ class PkiScriptlet(pkiscriptlet.AbstractBasePkiScriptlet): deployer.mdict['pki_instance_configuration_path'], ignore_cb=file_ignore_callback_src_server) + # Link /etc/pki//logging.properties + # to /usr/share/pki/server/conf/logging.properties. + deployer.symlink.create( + os.path.join(deployer.mdict['pki_source_server_path'], "logging.properties"), + os.path.join(deployer.mdict['pki_instance_configuration_path'], + "logging.properties")) + # create /etc/sysconfig/ deployer.file.copy_with_slot_substitution( deployer.mdict['pki_source_tomcat_conf'], @@ -219,5 +226,10 @@ def file_ignore_callback_src_server(src, names): config.pki_log.info(log.FILE_EXCLUDE_CALLBACK_2, src, names, extra=config.PKI_INDENTATION_LEVEL_1) - excludes = {'schema.ldif', 'database.ldif', 'manager.ldif', 'pki.xml'} - return excludes + return { + 'schema.ldif', + 'database.ldif', + 'manager.ldif', + 'pki.xml', + 'logging.properties' + } diff --git a/base/server/share/conf/logging.properties b/base/server/share/conf/logging.properties index dfdc0a4..7c1ac37 100644 --- a/base/server/share/conf/logging.properties +++ b/base/server/share/conf/logging.properties @@ -21,28 +21,11 @@ handlers = 1catalina.org.apache.juli.FileHandler, 2localhost.org.apache.juli.FileHandler, 3manager.org.apache.juli.FileHandler, 4host-manager.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler -.handlers = 1catalina.org.apache.juli.FileHandler, java.util.logging.ConsoleHandler - ############################################################ # Handler specific properties. # Describes specific configuration info for Handlers. ############################################################ -# Change the following settings to allow for more granular debugging: -# -# * 1catalina.org.apache.juli.FileHandler.level = ALL -# * 2localhost.org.apache.juli.FileHandler.level = ALL -# -# and add the following lines to the end of this file: -# -# * org.apache.catalina.loader.level = FINEST -# * org.apache.catalina.loader.WebappClassLoader.level = FINEST -# * org.apache.catalina.loader.StandardClassLoader.level = FINEST -# * com.netscape.cms.servlet.base.level = FINEST -# * com.netscape.cms.servlet.base.CMSStartServlet.level = FINEST -# * java.net.URLClassLoader.level = FINEST -# - 1catalina.org.apache.juli.FileHandler.level = FINE 1catalina.org.apache.juli.FileHandler.directory = ${catalina.base}/logs 1catalina.org.apache.juli.FileHandler.prefix = catalina. @@ -59,15 +42,18 @@ handlers = 1catalina.org.apache.juli.FileHandler, 2localhost.org.apache.juli.Fil 4host-manager.org.apache.juli.FileHandler.directory = ${catalina.base}/logs 4host-manager.org.apache.juli.FileHandler.prefix = host-manager. -java.util.logging.ConsoleHandler.level = FINE +java.util.logging.ConsoleHandler.level = ALL java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter - +java.util.logging.SimpleFormatter.format = %4$s: %5$s%6$s%n ############################################################ # Facility specific properties. # Provides extra control for each logger. ############################################################ +.level = WARNING +.handlers = java.util.logging.ConsoleHandler + org.apache.catalina.core.ContainerBase.[Catalina].[localhost].level = INFO org.apache.catalina.core.ContainerBase.[Catalina].[localhost].handlers = 2localhost.org.apache.juli.FileHandler -- 1.8.3.1 From c7f0585680dbfdd0019da6d2713dc9b1ded42761 Mon Sep 17 00:00:00 2001 From: "Endi S. Dewata" Date: Thu, 17 Nov 2016 03:41:25 +0100 Subject: [PATCH 4/8] Updated log4j.properties. To reduce maintenance the log4j.properties is no longer copied into the instance folder during deployment. Instead, a link will be created in the /var/lib/pki//lib folder pointing to the default file in /usr/share/pki/server/conf. The default log4j.properties has been updated to remove redundant lines. By default only log messages with level WARN or higher will be logged on the console. https://fedorahosted.org/pki/ticket/1897 (cherry picked from commit bfd7fc1c9ec665b4affda5bf48c9aca20f8f5775) (cherry picked from commit 4f381a0832ec069370f9461aabbbd1033371d6b0) --- .../deployment/scriptlets/instance_layout.py | 7 +++- base/server/share/conf/log4j.properties | 45 ++++++++++------------ 2 files changed, 27 insertions(+), 25 deletions(-) diff --git a/base/server/python/pki/server/deployment/scriptlets/instance_layout.py b/base/server/python/pki/server/deployment/scriptlets/instance_layout.py index 07eecbd..330aa46 100644 --- a/base/server/python/pki/server/deployment/scriptlets/instance_layout.py +++ b/base/server/python/pki/server/deployment/scriptlets/instance_layout.py @@ -139,8 +139,12 @@ class PkiScriptlet(pkiscriptlet.AbstractBasePkiScriptlet): os.path.join( deployer.mdict['pki_instance_lib'], name)) + + # Link /var/lib/pki//lib/log4j.properties + # to /usr/share/pki/server/conf/log4j.properties. deployer.symlink.create( - deployer.mdict['pki_instance_conf_log4j_properties'], + os.path.join(deployer.mdict['pki_source_server_path'], + "log4j.properties"), deployer.mdict['pki_instance_lib_log4j_properties']) # Link /var/lib/pki//common to /usr/share/pki/server/common @@ -231,5 +235,6 @@ def file_ignore_callback_src_server(src, names): 'database.ldif', 'manager.ldif', 'pki.xml', + 'log4j.properties', 'logging.properties' } diff --git a/base/server/share/conf/log4j.properties b/base/server/share/conf/log4j.properties index dd4bd93..43b6009 100644 --- a/base/server/share/conf/log4j.properties +++ b/base/server/share/conf/log4j.properties @@ -1,30 +1,27 @@ # --- BEGIN COPYRIGHT BLOCK --- -# Copyright (C) 2012 Red Hat, Inc. +# Copyright (C) 2016 Red Hat, Inc. # All rights reserved. # Modifications: configuration parameters # --- END COPYRIGHT BLOCK --- -log4j.rootLogger=debug, R -log4j.appender.R=org.apache.log4j.RollingFileAppender -log4j.appender.R.File=${catalina.base}/logs/catalina.out -log4j.appender.R.MaxFileSize=10MB -log4j.appender.R.MaxBackupIndex=10 -log4j.appender.R.layout=org.apache.log4j.PatternLayout -log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n -log4j.logger.org.apache.catalina=DEBUG, R -log4j.logger.org.apache.catalina.core.ContainerBase.[Catalina].[localhost]=DEBUG, R -log4j.logger.org.apache.catalina.core=DEBUG, R -log4j.logger.org.apache.catalina.session=DEBUG, R +# 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. -#resteasy -log4j.appender.stdout=org.apache.log4j.ConsoleAppender -log4j.appender.stdout.Target=System.out -log4j.appender.stdout.layout=org.apache.log4j.PatternLayout -log4j.appender.stdout.layout.ConversionPattern=%d{ABSOLUTE} %5p (%c:%L) - %m%n -log4j.rootLogger=warn, stdout -log4j.rootCategory=debug, stdout -log4j.category.org.jboss.resteasy.core=debug -log4j.category.org.jboss.resteasy.plugins.providers=debug -log4j.category.org.jboss.resteasy.specimpl=debug -log4j.category.org.jboss.resteasy.plugins.server=debug -log4j.logger.org.jboss.resteasy.mock=debug +log4j.appender.console = org.apache.log4j.ConsoleAppender +log4j.appender.console.Target = System.err +log4j.appender.console.layout = org.apache.log4j.PatternLayout +log4j.appender.console.layout.ConversionPattern = %p: %m%n + +log4j.rootLogger = WARN, console -- 1.8.3.1 From 730880bbd32aca11d5dd075c25aca68a8840b883 Mon Sep 17 00:00:00 2001 From: "Endi S. Dewata" Date: Tue, 8 Nov 2016 16:42:01 +0100 Subject: [PATCH 5/8] Added man pages for logging configuration. New man pages have been added for the common and server logging configurations. https://fedorahosted.org/pki/ticket/1897 (cherry picked from commit dbff34d56615e888823c89a4a4f6d476bb1ccf17) (cherry picked from commit 751df721c158f98320d6abc37ef4380acf29a42a) --- base/common/man/man5/pki-logging.5 | 94 +++++++++++++++ base/common/share/etc/logging.properties | 2 - base/server/man/man5/pki-server-logging.5 | 191 ++++++++++++++++++++++++++++++ 3 files changed, 285 insertions(+), 2 deletions(-) create mode 100644 base/common/man/man5/pki-logging.5 create mode 100644 base/server/man/man5/pki-server-logging.5 diff --git a/base/common/man/man5/pki-logging.5 b/base/common/man/man5/pki-logging.5 new file mode 100644 index 0000000..ab37402 --- /dev/null +++ b/base/common/man/man5/pki-logging.5 @@ -0,0 +1,94 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-logging 5 "November 3, 2016" "version 10.3" "PKI Common Logging Configuration" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-logging \- PKI Common Logging Configuration + +.SH LOCATION +/usr/share/pki/etc/logging.properties, /etc/pki/logging.properties + +.SH DESCRIPTION + +PKI clients and tools use java.util.logging (JUL) as the logging framework +(see https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html). + +The default logging configuration is located at /usr/share/pki/etc/logging.properties. + +By default only log messages with level WARNING or higher will be logged on the console. + +.IP +.nf +java.util.logging.ConsoleHandler.level = ALL +java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter +java.util.logging.SimpleFormatter.format = %4$s: %5$s%6$s%n + +\[char46]level = WARNING +\[char46]handlers = java.util.logging.ConsoleHandler +.fi +.PP + +For more information see the following documents: + +.nf +- https://docs.oracle.com/javase/8/docs/api/java/util/logging/ConsoleHandler.html +- https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html +- https://docs.oracle.com/javase/8/docs/api/java/util/logging/SimpleFormatter.html +- https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html +.fi + +.SH CUSTOMIZATION + +To customize the logging configuration, copy the default logging configuration into a new location: + +$ cp /usr/share/pki/etc/logging.properties /etc/pki/logging.properties + +Then edit the file as needed. +For example, to troubleshoot issues with PKI library add the following lines: + +.IP +.nf +netscape.level = ALL +com.netscape.level = ALL +org.dogtagpki.level = ALL +.fi +.PP + +To troubleshoot issues with RESTEasy add the following line: + +.IP +.nf +org.jboss.resteasy.level = ALL +.fi +.PP + +Then specify the location of the custom logging configuration in the following parameter in /etc/pki/pki.conf: + +.IP +.nf +LOGGING_CONFIG=/etc/pki/logging.properties +.fi +.PP + +Then restart the application. + +.SH AUTHORS +Dogtag Team . + +.SH COPYRIGHT +Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + +.SH SEE ALSO +.BR pki-server-logging(5) diff --git a/base/common/share/etc/logging.properties b/base/common/share/etc/logging.properties index fe879c4..2a14c4e 100644 --- a/base/common/share/etc/logging.properties +++ b/base/common/share/etc/logging.properties @@ -19,8 +19,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -handlers = java.util.logging.ConsoleHandler - java.util.logging.ConsoleHandler.level = ALL java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter java.util.logging.SimpleFormatter.format = %4$s: %5$s%6$s%n diff --git a/base/server/man/man5/pki-server-logging.5 b/base/server/man/man5/pki-server-logging.5 new file mode 100644 index 0000000..9aed7d8 --- /dev/null +++ b/base/server/man/man5/pki-server-logging.5 @@ -0,0 +1,191 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-server-logging 5 "November 3, 2016" "version 10.3" "PKI Server Logging Configuration" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-server-logging \- PKI Server Logging Configuration + +.SH LOCATION +/etc/pki//logging.properties, /var/lib/pki//lib/log4j.properties, /etc/pki///CS.cfg + +.SH DESCRIPTION + +PKI server logging can be configured using the following logging frameworks: + +.nf +- java.util.logging (JUL) (https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html) +- Log4j (http://logging.apache.org/log4j/1.2/) +- Internal Logging +.fi + +.SS java.util.logging (JUL) + +Tomcat uses JUL as the default logging framework. +The configuration is described in http://tomcat.apache.org/tomcat-7.0-doc/logging.html and http://tomcat.apache.org/tomcat-8.0-doc/logging.html. + +The default configuration is located at /usr/share/pki/server/conf/logging.properties. +During server deployment a link will be created at /etc/pki//logging.properties. + +By default only log messages with level WARNING or higher will be logged on the console (i.e. systemd journal). + +.IP +.nf +java.util.logging.ConsoleHandler.level = ALL +java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter +java.util.logging.SimpleFormatter.format = %4$s: %5$s%6$s%n + +\[char46]level = WARNING +\[char46]handlers = java.util.logging.ConsoleHandler +.fi +.PP + +The systemd journal can be viewed with the following command: + +.nf +$ journalctl -u pki-tomcatd@.service +.fi + +For more information see the following documents: + +.nf +- https://docs.oracle.com/javase/8/docs/api/java/util/logging/ConsoleHandler.html +- https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html +- https://docs.oracle.com/javase/8/docs/api/java/util/logging/SimpleFormatter.html +- https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html +.fi + +.SS Log4j + +The default Tomcat 7 classpath does include Log4j, but the server itself is not configured to use Log4j for logging by default. +However, since the Log4j is in the classpath the RESTEasy will use Log4j for logging automatically (see https://docs.jboss.org/resteasy/docs/3.0.6.Final/userguide/html/Installation_Configuration.html#RESTEasyLogging). + +The default Log4j configuration is located at /usr/share/pki/server/conf/log4j.properties. +During server deployment a link will be created at /var/lib/pki//lib/log4j.properties. + +By default only log messages with level WARN or higher will be logged on the console (i.e. systemd journal). + +.IP +.nf +log4j.appender.console = org.apache.log4j.ConsoleAppender +log4j.appender.console.Target = System.err +log4j.appender.console.layout = org.apache.log4j.PatternLayout +log4j.appender.console.layout.ConversionPattern = %p: %m%n + +log4j.rootLogger = WARN, console +.fi +.PP + +The default Tomcat 8 classpath does not include Log4j, so RESTEasy will use JUL instead. + +For more information see the following documents: + +.nf +- http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/ConsoleAppender.html +- http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/Level.html +- http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html +.fi + +.SS Internal Logging + +Each PKI subsystem uses an internal logging framework for debugging purposes. + +The logging configuration is stored in /etc/pki///CS.cfg. + +.IP +.nf +debug.enabled=true +debug.level=0 +debug.filename=/var/lib/pki//logs//debug +debug.hashkeytypes= +debug.showcaller=false +.fi +.PP + +The \fBdebug.enabled\fP determines whether the debug log is enabled. By default it is enabled. + +The \fBdebug.level\fP determines the amount of details to be logged. The value ranges from 0 (most details) to 10 (least details). The default is 0. + +The \fBdebug.filename\fP determines the debug log file location. By default it is located at /var/lib/pki//logs//debug. + +The \fBdebug.hashkeytypes\fP is a comma-separated list of additional components to log. By default it's empty. + +The \fBdebug.showcaller\fP determines whether to include the caller information in the log message. By default it's disabled. + +.SH CUSTOMIZATION + +.SS java.util.logging (JUL) + +To customize JUL configuration, replace the link with a copy of the default configuration: + +.nf +$ rm -f /etc/pki//logging.properties +$ cp /usr/share/pki/server/conf/logging.properties /etc/pki/ +$ chown pkiuser.pkiuser /etc/pki//logging.properties +.fi + +Then edit the file as needed. +For example, to troubleshoot issues with PKI library add the following lines: + +.IP +.nf +netscape.level = ALL +com.netscape.level = ALL +org.dogtagpki.level = ALL +.fi +.PP + +To troubleshoot issues with RESTEasy add the following line (unless Log4j is installed in Tomcat classpath): + +.IP +.nf +org.jboss.resteasy.level = ALL +.fi +.PP + +Then restart the server. + +.SS Log4j + +To customize Log4j configuration, replace the link with a copy of the default configuration: + +.nf +$ rm -f /var/lib/pki//lib/log4j.properties +$ cp /usr/share/pki/server/conf/log4j.properties /var/lib/pki//lib +$ chown pkiuser.pkiuser /var/lib/pki//lib/log4j.properties +.fi + +Then edit the file as needed. +For example, to troubleshoot issues with RESTEasy add the following line (unless Log4j is not installed in Tomcat classpath): + +.IP +.nf +log4j.logger.org.jboss.resteasy = ALL +.fi +.PP + +Then restart the server. + +.SS Internal Logging + +To customize the internal logging configuration, edit the CS.cfg as needed, then restart the server. + +.SH AUTHORS +Dogtag Team . + +.SH COPYRIGHT +Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + +.SH SEE ALSO +.BR pki-logging(5) -- 1.8.3.1 From f76d73502c7b013f0fe7eb3b5665553a8005ad02 Mon Sep 17 00:00:00 2001 From: "Endi S. Dewata" Date: Sat, 29 Oct 2016 07:53:02 +0200 Subject: [PATCH 7/8] Added man pages for PKCS #12 utilities. New man pages have been added: pki-pkcs12, pki-pkcs12-cert, and pki-pkcs12-key. https://fedorahosted.org/pki/ticket/1920 (cherry picked from commit e8b2aa675f617efd2d40984651e0b501dc334690) (cherry picked from commit 580410f5b2a90a46b0a456c2a6c8523e56e55f77) --- base/java-tools/man/man1/pki-pkcs12-cert.1 | 122 +++++++++++++++++++++++++++++ base/java-tools/man/man1/pki-pkcs12-key.1 | 76 ++++++++++++++++++ base/java-tools/man/man1/pki-pkcs12.1 | 114 +++++++++++++++++++++++++++ 3 files changed, 312 insertions(+) create mode 100644 base/java-tools/man/man1/pki-pkcs12-cert.1 create mode 100644 base/java-tools/man/man1/pki-pkcs12-key.1 create mode 100644 base/java-tools/man/man1/pki-pkcs12.1 diff --git a/base/java-tools/man/man1/pki-pkcs12-cert.1 b/base/java-tools/man/man1/pki-pkcs12-cert.1 new file mode 100644 index 0000000..8a94de7 --- /dev/null +++ b/base/java-tools/man/man1/pki-pkcs12-cert.1 @@ -0,0 +1,122 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-pkcs12-cert 1 "Oct 28, 2016" "version 10.3" "PKI PKCS #12 Certificate Management Commands" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-pkcs12-cert \- Command-Line Interface for managing individual certificates in PKCS #12 file. + +.SH SYNOPSIS +.nf +\fBpki\fR [CLI options] \fBpkcs12-cert\fR +\fBpki\fR [CLI options] \fBpkcs12-cert-find\fR [command options] +\fBpki\fR [CLI options] \fBpkcs12-cert-export \fR [command options] +\fBpki\fR [CLI options] \fBpkcs12-cert-add \fR [command options] +\fBpki\fR [CLI options] \fBpkcs12-cert-mod \fR [command options] +\fBpki\fR [CLI options] \fBpkcs12-cert-del \fR [command options] +.fi + +.SH DESCRIPTION +.PP +The \fBpki pkcs12-cert\fR commands provide command-line interfaces to manage certificates in a PKCS #12 file. + +.PP +\fBpki\fR [CLI options] \fBpkcs12-cert-find\fR [command options] +.RS 4 +This command is to list certificates in a PKCS #12 file. +.RE +.PP +\fBpki\fR [CLI options] \fBpkcs12-cert-export \fR [command options] +.RS 4 +This command is to export a certificate from a PKCS #12 file. +.RE +.PP +\fBpki\fR [CLI options] \fBpkcs12-cert-add \fR [command options] +.RS 4 +This command is to add a certificate into a PKCS #12 file. +.RE +.PP +\fBpki\fR [CLI options] \fBpkcs12-cert-mod \fR [command options] +.RS 4 +This command is to modify a certificate in a PKCS #12 file. +.RE +.PP +\fBpki\fR [CLI options] \fBpkcs12-cert-del \fR [command options] +.RS 4 +This command is to delete a certificate from a PKCS #12 file. +.RE + +.SH OPTIONS +The CLI options are described in \fBpki\fR(1). + +.SH OPERATIONS + +To view available profile commands, type \fBpki pkcs12-cert\fP. To view each command's usage, type \fB pki pkcs12-cert- \-\-help\fP. + +All \fBpkcs12-cert\fP commands require a PKCS #12 file and its password. +The PKCS #12 file can be specified with the \fB--pkcs12-file\fP parameter. +The password can be specified either directly with the \fB--pkcs12-password\fP parameter, or in a file with the \fB--pkcs12-password-file\fP parameter. + +Some \fBpki pkcs12-cert\fP commands require an NSS database and its password. +The NSS database location can be specified with the \fB-d\fP parameter (default: ~/.dogtag/nssdb). +The NSS database password can be specified with the \fB-c\fP or the \fB-C\fP parameter. + +.SS Viewing certificates in a PKCS #12 file + +To list the certificates in a PKCS #12 file: + +.B pki pkcs12-cert-find + +.SS Exporting a certificate from a PKCS #12 file + +To export a certificate from a PKCS #12 file into a file in PEM format: + +.B pki pkcs12-cert-export + +The certificate file can be specified with the \fB--cert-file\fP parameter. + +.SS Adding a certificate from an NSS database into a PKCS #12 file + +To add a certificate including its key and trust flags from an NSS database into a PKCS #12 file: + +.B pki pkcs12-cert-add + +If the PKCS #12 file does not exist, it will be created automatically. +If the PKCS #12 file already exists, the certificate will be added into the file. + +The trust flags can be overwritten with the \fB--trust-flags\fP parameter. +If the key is not needed, specify the \fB--no-key\fP parameter. + +.SS Modifying a certificate in a PKCS #12 file + +To modify the trust flags of a certificate in a PKCS #12 file: + +.B pki pkcs12-cert-mod + +The trust flags can be specified with the \fB--trust-flags\fP parameter. + +.SS Deleting a certificate from a PKCS #12 file + +To delete a certificate and its key from a PKCS #12 file: + +.B pki pkcs12-cert-del + +.SH AUTHORS +Endi S. Dewata . + +.SH COPYRIGHT +Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + +.SH SEE ALSO +.BR pki-pkcs12(1) diff --git a/base/java-tools/man/man1/pki-pkcs12-key.1 b/base/java-tools/man/man1/pki-pkcs12-key.1 new file mode 100644 index 0000000..884278d --- /dev/null +++ b/base/java-tools/man/man1/pki-pkcs12-key.1 @@ -0,0 +1,76 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-pkcs12-key 1 "Oct 28, 2016" "version 10.3" "PKI PKCS #12 Key Management Commands" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-pkcs12-key \- Command-Line Interface for managing individual keys in PKCS #12 file. + +.SH SYNOPSIS +.nf +\fBpki\fR [CLI options] \fBpkcs12-key\fR +\fBpki\fR [CLI options] \fBpkcs12-key-find\fR [command options] +\fBpki\fR [CLI options] \fBpkcs12-key-del \fR [command options] +.fi + +.SH DESCRIPTION +.PP +The \fBpki pkcs12-key\fR commands provide command-line interfaces to manage keys in a PKCS #12 file. + +.PP +\fBpki\fR [CLI options] \fBpkcs12-key-find\fR [command options] +.RS 4 +This command is to list keys in a PKCS #12 file. +.RE +.PP +\fBpki\fR [CLI options] \fBpkcs12-key-del \fR [command options] +.RS 4 +This command is to delete a key from a PKCS #12 file. +.RE + +.SH OPTIONS +The CLI options are described in \fBpki\fR(1). + +.SH OPERATIONS + +To view available profile commands, type \fBpki pkcs12-key\fP. To view each command's usage, type \fB pki pkcs12-key- \-\-help\fP. + +All \fBpkcs12-key\fP commands require a PKCS #12 file and its password. +The PKCS #12 file can be specified with the \fB--pkcs12-file\fP parameter. +The password can be specified either directly with the \fB--pkcs12-password\fP parameter, or in a file with the \fB--pkcs12-password-file\fP parameter. + +All \fBpkcs12-key\fP commands also require an NSS database and its password. +The NSS database location can be specified with the \fB-d\fP parameter (default: ~/.dogtag/nssdb). +The NSS database password can be specified with the \fB-c\fP or the \fB-C\fP parameter. + +.SS Viewing keys in a PKCS #12 file + +To list the keys in a PKCS #12 file: + +.B pki pkcs12-key-find + +.SS Deleting a key from a PKCS #12 file + +To delete a key from a PKCS #12 file: + +.B pki pkcs12-key-del + +.SH AUTHORS +Endi S. Dewata . + +.SH COPYRIGHT +Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + +.SH SEE ALSO +.BR pki-pkcs12(1) diff --git a/base/java-tools/man/man1/pki-pkcs12.1 b/base/java-tools/man/man1/pki-pkcs12.1 new file mode 100644 index 0000000..5056930 --- /dev/null +++ b/base/java-tools/man/man1/pki-pkcs12.1 @@ -0,0 +1,114 @@ +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH pki-pkcs12 1 "Oct 28, 2016" "version 10.3" "PKI PKCS #12 Management Commands" Dogtag Team +.\" Please adjust this date whenever revising the man page. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for man page specific macros, see man(7) +.SH NAME +pki-pkcs12 \- Command-Line Interface for managing certificates and keys in PKCS #12 file. + +.SH SYNOPSIS +.nf +\fBpki\fR [CLI options] \fBpkcs12\fR +\fBpki\fR [CLI options] \fBpkcs12-export\fR [command options] +\fBpki\fR [CLI options] \fBpkcs12-import\fR [command options] +\fBpki\fR [CLI options] \fBpkcs12-cert\fR [command options] +\fBpki\fR [CLI options] \fBpkcs12-key\fR [command options] +.fi + +.SH DESCRIPTION +.PP +The \fBpki pkcs12\fR commands provide command-line interfaces to manage certificate and keys in a PKCS #12 file. + +.PP +\fBpki\fR [CLI options] \fBpkcs12-export\fR [command options] +.RS 4 +This command is to export all certificates and keys from an NSS database into a PKCS #12 file. +.RE +.PP +\fBpki\fR [CLI options] \fBpkcs12-import\fR [command options] +.RS 4 +This command is to import all certificates and keys from a PKCS #12 file into an NSS database. +.RE +.PP +\fBpki\fR [CLI options] \fBpkcs12-cert\fR [command options] +.RS 4 +This command is to manage individual certificates in a PKCS #12 file. See \fBpki-pkcs12-cert\fR(1). +.RE +.PP +\fBpki\fR [CLI options] \fBpkcs12-key\fR [command options] +.RS 4 +This command is to import individual keys in a PKCS #12 file. See \fBpki-pkcs12-key\fR(1). +.RE + +.SH OPTIONS +The CLI options are described in \fBpki\fR(1). + +.SH OPERATIONS + +To view available PKCS #12 commands, type \fBpki pkcs12\fP. To view each command's usage, type \fB pki pkcs12- \-\-help\fP. + +All \fBpki pkcs12\fP commands require a PKCS #12 file and its password. +The PKCS #12 file can be specified with the \fB--pkcs12-file\fP parameter. +The password can be specified either directly with the \fB--pkcs12-password\fP parameter, or in a file with the \fB--pkcs12-password-file\fP parameter. + +Some \fBpki pkcs12\fP commands require an NSS database and its password. +The NSS database location can be specified with the \fB-d\fP parameter (default: ~/.dogtag/nssdb). +The NSS database password can be specified with the \fB-c\fP or the \fB-C\fP parameter. + +.SS Exporting all certificates and keys into a PKCS #12 file + +To export all certificates and keys from an NSS database into a PKCS #12 file: + +.B pki pkcs12-export [nicknames...] + +By default the command will export all certificates in the NSS database. +To export certain certificates only, specify the certificate nicknames as separate arguments. + +By default the command will always create a new PKCS #12 file. +To export into an existing PKCS #12 file, specify the \fB--append\fP parameter. + +By default the command will include the certificate chain. +To export without certificate chain, specify the \fB--no-chain\fP parameter. + +By default the command will include the key of each certificate. +To export without the key, specify the \fB--no-key\fP parameter. + +By default the command will include the trust flags of each certificate. +To export without the trust flags, specify the \fB--no-trust-flags\fP parameter. + +.SS Importing certificates and keys from a PKCS #12 file + +To import certificates and keys from a PKCS #12 file into an NSS database: + +.B pki pkcs12-import + +By default the command will include all certificates in the PKCS #12 file. +To import without the CA certificates (certificates without keys), specify the \fB--no-ca-certs\fP parameter. +To import without the user certificates (certificates with keys), specify the \fB--no-user-certs\fP parameter. + +By default the command will skip a certificate if it already exists in the NSS database. +To overwrite the nickname, the key, and the trust flags of existing certificates, specify the \fB--overwrite\fP parameter. + +By default the command will include the trust flags of each certificate. +To import without the trust flags, specify the \fB--no-trust-flags\fP parameter. + +.SH AUTHORS +Endi S. Dewata . + +.SH COPYRIGHT +Copyright (c) 2016 Red Hat, Inc. This is licensed under the GNU General Public License, version 2 (GPLv2). A copy of this license is available at http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt. + +.SH SEE ALSO +.BR pki-pkcs12-cert(1), +.BR pki-pkcs12-key(1) -- 1.8.3.1