Merge pull request #462 from bareos/dev/fbergkemper/bareos-18.2/s2747

docs: document a critical bscan limitation (backport 18.2)

docs/manuals/source/Appendix/BareosPrograms.rst

@@ -790,6 +790,20 @@ After bscan
 If you use bscan to enter the contents of the Volume into an existing catalog, you should be aware that the records you entered may be immediately pruned during the next job, particularly if the Volume is very old or had been previously purged. To avoid this, after running bscan, you can manually set the volume status (VolStatus) to Read-Only by using the update command in the catalog. This will allow you to restore from the volume without having it immediately purged. When you have restored and
 backed up the data, you can reset the VolStatus to Used and the Volume will be purged from the catalog.
 
+.. limitation:: bscan: importing jobs with bscan may break the correct job chain order
+
+   The Start Of Session (SOS) record is a special record placed by the Storage daemon on the storage medium as the first record of an append session job with a File daemon.
+   This record is needed for finding the beginning of a particular session (Job), since no records with the same VolSessionId and VolSessionTime will precede this record.
+   This record is not normally visible outside of the Storage daemon.
+   The Begin Session Label is similar to the Volume Label except that it contains additional information pertaining to the Session.
+
+   Having just a single timestamp generated by the SD in the SOS record is a limitation because there's currently no way for bscan to be aware of a jobs SchedTime, StartTime, EndTime, RealEndTime and JobTDate.
+   Those values are required to keep the historical and correct order of a CopyJob, a MigrationJob or a VirtualFull.
+
+   Due to this fact timestamps of a CopyJob, a MigrationJob or a VirtualFull will always differ from the timestamp in the original catalog after using bscan.
+
+   Please be aware that this can lead to serious problems when using the Always Incremental backup scheme for example.
+
 
 .. _bcopy: