====== AhsayOBM Backup Source File Filter Guide ======
Last Revision: 2nd April 2019 \\ Applicable version: 7 and above

{{public:documents_and_guides:obm:backup-source-filter:filter-front.png}}

====== 1. About filtering ======

Filters can be used to search for files or folders that will be included or excluded in the backup.  The user can specify criteria that will be used to filter out files/folders.
Some key points to understand before reading this guide:
  * AhsayOBM and AhsayACB filters checks the whole filename including the filename extension.  For example, you have a document with filename ‘employees’ so if ends with s is your filter then this file will not be included in the backup since its whole filename is ‘employees.doc’ or ‘employees.docx’ with both files not ending in s but c and x respectively.  Your OS may, by default, hide file extensions.  For further reference regarding showing file extensions, please refer to the following websites: http://kb.winzip.com/kb/entry/26/ or https://www.thewindowsclub.com/show-file-extensions-in-windows.
  * This document may make references to regular expression patterns.  Regular expression patterns are case-sensitive.  For example, your pattern to match is ‘^a.*\.xls$’, will only match filenames starting with lower case letter a, but not filenames with upper case letter A.  For further reference regarding regular expressions please refer to the following websites:  https://docs.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference, https://medium.com/factory-mind/regex-tutorial-a-simple-cheatsheet-by-examples-649dc1c3f285, http://nebc.nerc.ac.uk/courses/perl_bioperl/regex.pdf, and http://www.cbs.dtu.dk/courses/27610/regular-expressions-cheat-sheet-v2.pdf
  * This guide will assume you do not have any preempted values which may hide or disable certain features.  If you encounter your UI does not exactly match the screenshots in the guide, this may explain the discrepancy.  You may need to contact your AhsayCBS system administrator for consultation.
  * Please note that inclusion or exclusion made by filter takes precedence over backup source selection.

===== What are the requirements? =====
In order to create a backup set with filter, requirements are essential to avoid any interruptions upon running the backup set.

==== Network connection ====
You need to have a network connection for backup sets with filters that has Windows shared folder as source destination. This is applicable for Windows OS and Linux / FreeBSD OS.

==== Account rights ====
On Windows OS, for running AhsayOBM (GUI) / AhsayACB. you need to have administrator rights to allow you to view files on the server and for running AhsayOBM (CLI). This will allow you to check if the filter criteria are correct. While on Linux/ FreeBSD OS you need to login as root to access the AhsayOBM – GUI and CLI.
 
===== What are the limitations? =====
There are limitations in creating a backup set with filters on various Operating System. Below are some of the limitations of Linux / FreeBSD OS:

==== Linux / FreeBSD OS ====
  * Creation of backup set with filters is not supported using backupSet.xml.
  * Creation of backup set with filters that has simple comparison as pattern is not supported using backupSet.xml.
  * Creation of backup set with filters that has regular expression UNIX-style as pattern is not supported using backupSet.xml.
  * Creation of backup set with filters in continuous backup is not supported. As continuous backup is only supported on Windows OS.
  * Preview is available on Linux/ FreeBSD OS if AhsayOBM is running in GUI environment. You can still check the result of your backup set with filters by checking the report and log. Refer to Ch. 5.3 Verify the backup report and logs.

===== What are the recommendations? =====
Here are some recommendations to make the backup set with filter more efficient and to maximize the full potential of the said feature.
  * When creating a backup set with filters, make sure that the filters you set does not conflict with each other.
  * Filters will be applied in creation order.
  * When creating a backup set with filters, make sure to fill up the Deselected Source field.
For Linux/ FreeBSD OS, ensure that these paths have been added:
    * /root/.obm
    * /usr/local/obm
    * /root/temp

<WRAP info>
The /root/temp is just a sample for reference purposes only. This will depend on your actual temporary folder path.

These are also the non-regular files/folders such as device files, block files, virtual files systems, pseudo file systems, etc. will be automatically ignored if selected for backup. Backup log entries of these files/folders will not appear in the backup logs.

Here are some examples: \\ /proc  \\ /dev \\ /sys \\ /run
</WRAP>