ADSS A U T O F I L E P R O C E S S O R (AFP)

Transcription

1 ADSS A U T O F I L E P R O C E S S O R (AFP) The Essential Guide to System Recovery A S C E R T I A LTD J A N U A R Y D O C U M E N T V E R S I O N Ascertia Limited. All rights reserved. This document contains commercial-in-confidence material. It must not be disclosed to any third party without the written authority of Ascertia Limited. Commercial-in-Confidence

2 Contents 1 Introduction Technical Support Conventions ADSS AFP Failure Scenarios Document Structure Host System Operating System ADSS AFP Service/Daemon Log Files ADSS AFP Source Folders Proxy Configuration Network Connectivity to ADSS Server Cloud Service Client Authentication Client TLS Authentication ADSS Server Cloud Service Cloud Service Web Browser Authentication Test Sample Test File Appendix A Host adss-us Host adss-us Ascertia Limited Commercial-in-Confidence Page 2 of 15

3 1 Introduction This is a vital guide for anyone managing one or more production ADSS Auto File Processor (AFP) instances. The document describes potential failure scenarios associated with ADSS AFP production servers and provides guidance on how these can be analysed and resolved. This document assumes that you have a production environment with one or more ADSS AFP instances that were previously operating perfectly and suddenly a system failure has occurred. This guide provides a comprehensive set of checks that can be made to identify the failure issue(s) and get ADSS AFP running once more. It is not intended to be used as configuration guide or general diagnostic help guide or checking test/development servers where configuration changes may have caused the issue, although it may be helpful in this regard. Resolving production server failures is often difficult with feature-rich applications such as ADSS AFP, especially when multiple third-party components are involved. This guide provides guidance and tips for issue identification and resolution in clear, logical steps. From experience, most sudden issues with a stable production system are caused by problems within the external systems, applications, or services that ADSS AFP relies upon. These tend to manifest themselves as a problem within ADSS AFP, but a quick examination of the relevant service logs will reveal whether an external issue is affecting ADSS AFP s ability to give an accurate and reliable answer. 1.1 Technical Support If technical support is required, Ascertia has a dedicated support team that provides debug, integration assistance and general customer support. Ascertia Support can be accessed in the following ways: Website Knowledge Base FAQs support@ascertia.com In addition to the support service described above, Ascertia provides formal support agreements with all product sales. Please contact sales@ascertia.com for more details. When sending support queries to Ascertia Support team, include all relevant ADSS AFP logs. Collect logs for last two days or from the date since the problems began. This will greatly assist the support team and help towards a speedy resolution. Logs are found in the <AFP Home>/logs directory. 1.2 Conventions The following typographical conventions are used in this guide to help locate and identify information: Bold text identifies menu names, menu options, items you can click on the screen, file names, folder names, and keyboard keys. Courier New font identifies code and text that appears on the command line. Bold Courier New identifies commands that you are required to type in. Ascertia Limited Commercial-in-Confidence Page 3 of 15

4 2 ADSS AFP Failure Scenarios A failure in ADSS AFP can result from a number of possible issues. These can be categorised to aid problem resolution, as follows: Issues with the underlying operating system and host - including CPU, memory or disk space. Infrastructure issues that prevent access to cloud services from ADSS AFP instances. These could be firewall or network related for example. ADSS AFP configuration an operator driven change to the configuration of any of the ADSS AFP profiles or generic settings. ADSS AFP relies on server side (cloud) services to operate. This is the hosted service where hashes for example, are sent for signature. Therefore, a failure in ADSS AFP may not be related to ADSS AFP at all. This document covers checks and tests to check for this type of apparent failure. 2.1 Document Structure Section 3 discusses how to check the ADSS AFP host system. Section 4 discusses the host ADSS Server Cloud Service that AFP relies on. Appendices contain copies of the sample afp.xml files used to test the cloud service referenced in Section 4. Ascertia Limited Commercial-in-Confidence Page 4 of 15

5 3 Host System As with any software application ADSS AFP relies on an operating system and the physical or virtual platform. Errors to the hardware such as physical component failure are obvious. However, for requesting client applications, a network timeout or similar failure would be observed with no obvious reason as to the cause. Physical errors of components or failure of the operating system can be caused by numerous problems. Rectifying these is outside the scope of this document. However, summary information is presented to check if the host and operating system are functioning as expected. There are certain elements to check if you suspect an underlying hardware or operating system issue. 3.1 Operating System Check the system memory, and network and CPU utilization using operating system tools. ADSS AFP requires minimal system resources. However, this does not preclude such a check when there are issues. By default, ADSS AFP requires a minimum of 128MB of RAM to function with an upper limit of 1GB, although high load or high throughput deployments require more. In such scenarios the <AFP Home>/conf/wrapper.conf is edited and the memory requirement increased. Check this file when looking at system resource usage. High CPU or RAM usage by ADSS AFP indicates the system is under stress, and more resources are required. This does not always translate to more CPU or RAM. For example, it could be an exhaustion caused by file locking by two separate ADSS AFP instances. Check that the disk space has not been consumed by an inappropriate ADSS AFP logging level. The default logging in the logs is normally set to INFO level but for high use environments this can produce too much information and for such environments the logging level ERROR should be used. DEBUG level should never be used on production systems. None of the ADSS AFP instances should be continuously consuming high levels of CPU. 3.2 ADSS AFP Service/Daemon Ensure that the ADSS AFP instance is running. On Windows this is: Ascertia-AFP For Linux systems the instance is deployed as a regular daemon and registered in /etc/init.d as: wrapper.ascertia-afp If this service is not running, then refer to the local log file. Log files are located under the directory: <AFP_HOME>/logs. There are usually multiple files in these folders, one for each day. The latest files from the current day are those which do not have a date appended to their name. Note on Windows there is only Service, but on Linux based systems there are two services created when using the daemon to control start-up and shutdown. 3.3 Log Files ADSS AFP logs to <AFP_HOME>/logs directory. The logs are rolled over every twenty-four hours by default but this can be changed using the <AFP_Home>/conf/log.properties file. In this file the standard log4j configuration is used. Refer to Apache Log4j project if there are major changes required to this configuration. For example, to use a syslog appender as opposed to the default file Ascertia Limited Commercial-in-Confidence Page 5 of 15

6 one. If you are experiencing issues open the log.properties file and change the following line as shown: - log4j.logger.com.ascertia=info,drfile1 to log4j.logger.com.ascertia=debug,drfile1 Save the file and restart the ADSS AFP Service or daemon. The directory contains two log files. The first is ADSS AFP audit trail titled afp.log by default (again this can be changed by editing the log.properties file if required), and the second, is wrapper.<date>.log. The wrapper log file is only present if you are running ADSS AFP via a Windows Service or Linux daemon. If you start ADSS AFP using the command line and afp.bat or afp.sh script, then this will not be present. This log file contains low level information about the start-up and shutdown of the service. 3.4 ADSS AFP Source Folders ADSS AFP is a watched folder application as its name implies. Each profile in the afp.xml file contains input, output, and error folder locations. These are UNC address format locations. The input folder is where ADSS AFP reads its input data for processing from and the other two are output folders for processed documents. Output is for successful processing and error for everything else. If files are found in the error folder, then the instance is not functioning as intended. In this instance refer to the log files for further investigation. The correct permissions must be in place in order to allow the ADSS AFP service owner to access the specified file locations. If unsure, have the system administrator verify access to the specified folders. Note there could be different folders per AFP profile, and sub-folders may be in use. Here is an example: - <Profiles> <Profile status="enable" localhash="true" type="signing" name="localhashing_pades_part2_ltv"> <InputFolderPath>../data/input_folder</InputFolderPath> <OutputFolderPath>../data/output_folder</OutputFolderPath> <ErrorFolderPath>../data/error_folder</ErrorFolderPath> <ScanSubDirectories delete="false">false</scansubdirectories> <!--Set attribute delete="true" to delete sub folders--> 3.5 Proxy Configuration The proxy configuration for ADSS AFP is used when there is a requirement for external communication. For example, to a watched folder across a network. In this instance, the proxy and interconnecting infrastructure is critical to the continued success of ADSS AFP functionality. The proxy is configured under ProxySettings under Global Configuration, i.e. AFP (see below). Although no internal test function exists for the proxy settings, it does provide the connection details that can be verified by the proxy owner. Connectivity can be tested using third party tools. For example, telnet client will indicate if the proxy can at least be reached. <Settings> <OriginatorId>Test_Client_ID</OriginatorId> <ServiceAddress> <PrimaryAddress> <SecondaryAddress> Ascertia Limited Commercial-in-Confidence Page 6 of 15

7 </ServiceAddress> <ProxySettings status="disable"> <ProxyHost> </ProxyHost> <ProxyPort>8090</ProxyPort> <Credentials status="enable"> <ProxyUserName>user1</ProxyUserName> <ProxyPassword>password1</ProxyPassword> <AuthenticationScheme>BASIC</AuthenticationScheme> <!--Possible values are: BASIC, DIGEST--> </Credentials> </ProxySettings> <ClientAuthPfxSettings status="enable"> <PfxFilePath>C:/temp/client.pfx</PfxFilePath> <PfxPassword>password2</PfxPassword> </ClientAuthPfxSettings> </Settings> Note proxy credentials, configuration and associated settings are outside the control of ADSS AFP. 3.6 Network Connectivity to ADSS Server Cloud Service ADSS AFP communicates with a cloud service hosted ADSS Server service. It relies on this to operate in nearly all scenarios (SigningHub and document conversion the two anomalies). ADSS Server Cloud Service is available on port Telnet or similar network tools should be used to test connectivity to these ports from ADSS AFP host. When unable to connect with the ADSS Server Cloud Service, verify simple network tests such as ping, telnet, and trace route from the ADSS AFP host system. 3.7 Client Authentication Authentication of ADSS AFP client to ADSS Server Cloud Service is done using a PFX file in combination with an originator or client ID. These are distributed to customers by Ascertia and referenced in the afp.xml file (OriginatorId is shown directly above and the PFX here): - <ClientAuthPfxSettings status="enable"> <PfxFilePath>C:/temp/client.pfx</PfxFilePath> <PfxPassword>password2</PfxPassword> </ClientAuthPfxSettings> First, check the setting is enabled. The default is disabled. Next ensure the path location and file name are correct and that the password is also correct. To check the password, import the PFX into your Windows or similar security store. When prompted enter the password to verify it. A successful import indicates the password is correct. For the OriginatorId make sure this value has not been changed or accidentally overwritten with the default value of samples_test_client. Ascertia Limited Commercial-in-Confidence Page 7 of 15

8 3.8 Client TLS Authentication The authentication of ADSS AFP client to ADSS Server Cloud Service is via client TLS, as described directly above. In order to trust the cloud service as with any TLS connection, the TLS certificate used to secure the cloud service must be trusted by the requesting client. For Ascertia services this means trusting the Ascertia Root CA 3 certificate. In order to verify this can be done by the ADSS AFP client, run the SSL configuration utility called ssl_trust_manager.bat/sh. This is located under directory <AFP_Home>/ssl. Here is a sample output from running the utility: The Ascertia Root CA 3 and Ascertia Internal CA3 certificate are required. If for some reason these are not present, then communication with the server will fail. The certificates are included under attachments of this PDF document. They are called: - Ascertia Root CA 3.txt Ascertia Internal CA 3.txt To use these files rename the files to use.cer or.der file extension before use. Alternatively, the file that the above utility updates is included in the attachment list of this document. It is called jssecacerts and is located under <AFP_Home>/jre/lib/security. If you choose to overwrite this file, you must restart ADSS AFP service for it to take effect. Again, the attachment must be renamed before use to remove the ".txt" extension. Ascertia Limited Commercial-in-Confidence Page 8 of 15

9 4 ADSS Server Cloud Service This section describes how to test the ADSS Server Cloud Service independently of your own ADSS AFP configuration. 4.1 Cloud Service Web Browser Authentication Test To test authentication to the cloud service, import your PFX into your local security store, as described above in section 3.7. Open a web browser on the same machine and navigate to one of these URLs: If the service is accessible you will be prompted to choose the certificate from your PFX file: - And if the certificate is valid you will see the following post selection: - Note this test can be done from any machine with a web browser and where you have successfully imported the PFX file. 4.2 Sample Test File Here are sample afp.xml files for both cloud services. To test using these files follow these steps: - 1. Stop your ADSS AFP instance. 2. Copy the PFX file (included in attachments to this document) to your local C:/temp directory. If using Linux based system copy to an appropriate file location and then edit the afp.xml file to refer to the new location. Remember you must rename the attached file extension from ".txt" to ".pfx" before use. This file is referenced in the afp.xml example files. ADSS AFP must be able to read it. The password is in the file already and does not require changing. For information purposes it is A1B2C3D4. Ascertia Limited Commercial-in-Confidence Page 9 of 15

10 3. Backup your afp.xml file from <AFP_Home>/conf directory. 4. Delete the current afp.xml file. 5. Copy the appropriate file from the attachments into <AFP_Home>/conf directory. 6. Start AFP service. 7. Copy the sample PDF (included in attachments to this document) into the input directory folder, i.e.../data/input_folder. Note the above assumes the directory <AFP_Home>/data/input_folder exists as per the default package. If it does not create it and apply the appropriate permissions for ADSS AFP owner. The test will hash the PDF locally and send the hash for signature to the respective ADSS Server Cloud Service. The output is written to the../data/output_folder. Ascertia Limited Commercial-in-Confidence Page 10 of 15

11 5 Appendix A Here are sample afp.xml files in full that are referenced in section 4 above. These are used to test the ADSS Server Cloud Service instances at and respectfully. Printed in full here in case the embedded files are not accessible. They are basically the same except for the order of the primary and secondary addresses of the ADSS Server Cloud Service. 5.1 Host adss-us1 <AFP> <Settings> <OriginatorId>Ascertia_Corporate_Test</OriginatorId> <ServiceAddress> <PrimaryAddress> <SecondaryAddress> </ServiceAddress> <ProxySettings status="disable"> <ProxyHost> </ProxyHost> <ProxyPort>8090</ProxyPort> <Credentials status="disable"> <ProxyUserName>user1</ProxyUserName> <ProxyPassword>password1</ProxyPassword> <AuthenticationScheme>BASIC</AuthenticationScheme> <!--Possible values are: BASIC, DIGEST--> </Credentials> </ProxySettings> <ClientAuthPfxSettings status="enable"> <PfxFilePath>C:/temp/Ascertia_Corporate_Test.pfx</PfxFilePath> <PfxPassword>A1B2C3D4</PfxPassword> </ClientAuthPfxSettings> </Settings> <Profiles> <Profile status="enable" localhash="true" type="signing" name="localhashing_pades_part2_ltv"> <InputFolderPath>../data/input_folder</InputFolderPath> <OutputFolderPath>../data/output_folder</OutputFolderPath> <ErrorFolderPath>../data/error_folder</ErrorFolderPath> <ScanSubDirectories delete="false">false</scansubdirectories> <!--Set attribute delete="true" to delete sub folders--> <SigningProfile>adss:signing:profile:003</SigningProfile> <HashAlgorithm>SHA256</HashAlgorithm> <!--Possible values are: SHA1,SHA256,SHA384,SHA512--> <HashMode>DETACHED</HashMode> <!--Possible values are: ENVELOPING, DETACHED--> <SigDictionarySize>80</SigDictionarySize> <!--Numeric value in KB e.g. 40--> Ascertia Limited Commercial-in-Confidence Page 11 of 15

12 <ConcurrentRequests>10</ConcurrentRequests> <BatchCount>30</BatchCount> must lock before processing starts--> <!--BatchCount defines the number of files that AFP <LockTimeout>120</LockTimeout> <!--The files locked by BatchCount are released after this number of seconds if not processed--> <IdleSleepTime>30</IdleSleepTime> <!--AFP sleeps for this number of seconds when there are no files left to process--> <ConnectionTimeout>30</ConnectionTimeout> <!--The ADSS Server connection is closed if communication fails for this number of seconds--> <FailureRetries>3</FailureRetries> <!--AFP tries this many times to re-establish the connection--> <FilePostfix>-processed</FilePostfix> <PdfSignatureSettings> <!--Remove PdfSignatureSettings to create invisible signatures--> -> <!--SigningPosition and SigningArea must not be used simultaneously in a profile- <SigningPosition>X1=80,Y1=78,X2=290,Y2=190</SigningPosition> <!--<SigningArea>TOP_LEFT</SigningArea>--> <!--Possible values are: TOP_LEFT, TOP_RIGHT, CENTER, BOTTOM_LEFT, BOTTOM_RIGHT--> <SignatureField>Signature-1</SignatureField> <!--Mandatory if SigningPosition is provided--> <SignatureAppearance>../data/resources/default_sig_appearance.xml</SignatureAppearance> <!--Mandatory if creating visible PDF signatures --> <SigningPage>1</SigningPage> <SigningReason>I am author of this document</signingreason> <SigningLocation>London</SigningLocation> <ContactInfo>support@ascertia.com</ContactInfo> <CompanyLogo>../data/resources/company_logo.png</CompanyLogo> <HandSignature>../data/resources/hand_signature.jpg</HandSignature> <CertifyPermission>CERTIFIED_FORM_FILLING_AND_ANNOTATIONS</CertifyPermission> <FontRepository>../data/resources/fonts</FontRepository> <SignedBy>Andy Amos</SignedBy> <SignerCertificate>../data/resources/samples_test_signing_certificate.cer</SignerCertificat e> </ PdfSignatureSettings> <!--<PdfProtection>--> <!--Optionally specify PDF data protection settings in the case of local hashing only. Note when sending the complete document to ADSS Server these permissions can be applied via signature profile settings on the server.--> <!--<PermissionsPassphrase>password</PermissionsPassphrase> <AllowPrinting> --> <Resolution>LOW</Resolution>--> <!-- Possible values are: HIGH, LOW <!--</AllowPrinting> <AllowModification>TRUE</AllowModification> <AllowCopyingAndExtraction>TRUE</AllowCopyingAndExtraction> <AllowDocumentAssembly>TRUE</AllowDocumentAssembly> <AllowTextAccess>TRUE</AllowTextAccess> <AllowFormFilling>TRUE</AllowFormFilling> Ascertia Limited Commercial-in-Confidence Page 12 of 15

13 <AllowCommenting>TRUE</AllowCommenting> </PdfProtection>--> <InputFileFilter> <FileExtension>pdf</FileExtension> <!--<FileNameContains>UK</FileNameContains>--> are required--> </InputFileFilter> <!--Use this element if filters </Profile> </Profiles> </AFP> 5.2 Host adss-us2 <AFP> <Settings> <OriginatorId>Ascertia_Corporate_Test</OriginatorId> <ServiceAddress> <PrimaryAddress> <SecondaryAddress> </ServiceAddress> <ProxySettings status="disable"> <ProxyHost> </ProxyHost> <ProxyPort>8090</ProxyPort> <Credentials status="disable"> <ProxyUserName>user1</ProxyUserName> <ProxyPassword>password1</ProxyPassword> <AuthenticationScheme>BASIC</AuthenticationScheme> <!--Possible values are: BASIC, DIGEST--> </Credentials> </ProxySettings> <ClientAuthPfxSettings status="enable"> <PfxFilePath>C:/temp/Ascertia_Corporate_Test.pfx</PfxFilePath> <PfxPassword>A1B2C3D4</PfxPassword> </ClientAuthPfxSettings> </Settings> <Profiles> <Profile status="enable" localhash="true" type="signing" name="localhashing_pades_part2_ltv"> <InputFolderPath>../data/input_folder</InputFolderPath> <OutputFolderPath>../data/output_folder</OutputFolderPath> <ErrorFolderPath>../data/error_folder</ErrorFolderPath> <ScanSubDirectories delete="false">false</scansubdirectories> <!--Set attribute delete="true" to delete sub folders--> <SigningProfile>adss:signing:profile:003</SigningProfile> Ascertia Limited Commercial-in-Confidence Page 13 of 15

14 <HashAlgorithm>SHA256</HashAlgorithm> <!--Possible values are: SHA1,SHA256,SHA384,SHA512--> <HashMode>DETACHED</HashMode> <!--Possible values are: ENVELOPING, DETACHED--> <SigDictionarySize>80</SigDictionarySize> <!--Numeric value in KB e.g. 40--> <ConcurrentRequests>10</ConcurrentRequests> <BatchCount>30</BatchCount> must lock before processing starts--> <!--BatchCount defines the number of files that AFP <LockTimeout>120</LockTimeout> <!--The files locked by BatchCount are released after this number of seconds if not processed--> <IdleSleepTime>30</IdleSleepTime> <!--AFP sleeps for this number of seconds when there are no files left to process--> <ConnectionTimeout>30</ConnectionTimeout> <!--The ADSS Server connection is closed if communication fails for this number of seconds--> <FailureRetries>3</FailureRetries> <!--AFP tries this many times to re-establish the connection--> <FilePostfix>-processed</FilePostfix> <PdfSignatureSettings> <!--Remove PdfSignatureSettings to create invisible signatures--> -> <!--SigningPosition and SigningArea must not be used simultaneously in a profile- <SigningPosition>X1=80,Y1=78,X2=290,Y2=190</SigningPosition> <!--<SigningArea>TOP_LEFT</SigningArea>--> <!--Possible values are: TOP_LEFT, TOP_RIGHT, CENTER, BOTTOM_LEFT, BOTTOM_RIGHT--> <SignatureField>Signature-1</SignatureField> <!--Mandatory if SigningPosition is provided--> <SignatureAppearance>../data/resources/default_sig_appearance.xml</SignatureAppearance> <!--Mandatory if creating visible PDF signatures --> <SigningPage>1</SigningPage> <SigningReason>I am author of this document</signingreason> <SigningLocation>London</SigningLocation> <ContactInfo>support@ascertia.com</ContactInfo> <CompanyLogo>../data/resources/company_logo.png</CompanyLogo> <HandSignature>../data/resources/hand_signature.jpg</HandSignature> <CertifyPermission>CERTIFIED_FORM_FILLING_AND_ANNOTATIONS</CertifyPermission> <FontRepository>../data/resources/fonts</FontRepository> <SignedBy>Andy Amos</SignedBy> <SignerCertificate>../data/resources/samples_test_signing_certificate.cer</SignerCertificate > </ PdfSignatureSettings> <!--<PdfProtection>--> <!--Optionally specify PDF data protection settings in the case of local hashing only. Note when sending the complete document to ADSS Server these permissions can be applied via signature profile settings on the server.--> <!--<PermissionsPassphrase>password</PermissionsPassphrase> <AllowPrinting> --> <Resolution>LOW</Resolution>--> <!-- Possible values are: HIGH, LOW <!--</AllowPrinting> <AllowModification>TRUE</AllowModification> Ascertia Limited Commercial-in-Confidence Page 14 of 15

15 <AllowCopyingAndExtraction>TRUE</AllowCopyingAndExtraction> <AllowDocumentAssembly>TRUE</AllowDocumentAssembly> <AllowTextAccess>TRUE</AllowTextAccess> <AllowFormFilling>TRUE</AllowFormFilling> <AllowCommenting>TRUE</AllowCommenting> </PdfProtection>--> <InputFileFilter> <FileExtension>pdf</FileExtension> <!--<FileNameContains>UK</FileNameContains>--> are required--> </InputFileFilter> <!--Use this element if filters </Profile> </Profiles> </AFP> *** End of Document *** Ascertia Limited Commercial-in-Confidence Page 15 of 15