Merge pull request #7 from ABCD-DEVCOM/docs-3.4

Update to version 3.4.x

Author: rogercgui

blog/2026-03-21-release-3-4-0.md

@@ -0,0 +1,49 @@
+---
+slug: 2026-03-21-release-3-4-0
+title: "ABCD 3.4.0 Technical Release Notes"
+authors: [fho4abcd ]
+tags: [release, v3.4.0]
+---
+
+## What's Changed
+* Branch for small issue by @fho4abcd in https://github.com/ABCD-DEVCOM/ABCD/pull/607
+* Improve client IP check by @fho4abcd in https://github.com/ABCD-DEVCOM/ABCD/pull/608
+* Add option to convert csv to iso-2709 by @fho4abcd in https://github.com/ABCD-DEVCOM/ABCD/pull/609
+* Improve IP check by @fho4abcd in https://github.com/ABCD-DEVCOM/ABCD/pull/610
+* Update inc_ip_check.php by @fho4abcd in https://github.com/ABCD-DEVCOM/ABCD/pull/611
+* Branch for small issue by @fho4abcd in https://github.com/ABCD-DEVCOM/ABCD/pull/612
+* Update institutional_info.php by @fho4abcd in https://github.com/ABCD-DEVCOM/ABCD/pull/613
+* Improvements to opac by @rogercgui in https://github.com/ABCD-DEVCOM/ABCD/pull/614
+
+<!-- truncate -->
+
+**Full Changelog**: https://github.com/ABCD-DEVCOM/ABCD/compare/v3.3.0...v3.4.0
+
+### Option to limit access to a database based on the IP address of the requestor.
+- The administrator can limit access by edit  of file 'the database to protect'/dr_path.def. This file may contain now new tag VALID_IP. The content of this tag is a comma separated list of internet IP addresses OR the keyword 'none'
+- An empty value or missing tag allows all IP addresses
+- Keyword 'none' limits the allowed IP addresses to link-local addresses or loopback addresses. Note that other keywords will have the same effect.
+- A value with valid IP addresses allows the link-local addresses + the entered IP addresses
+- If an IP address is not allowed then all actions for this database are blocked . Also for administrators !
+
+### Utility to convert a '.csv' file to a '.iso' file.
+- Found in Utilities &#8658; Export/Import
+- Can be helpfull for importing Excels lists with new records into ABCD
+- Unfortunately not suitable for UTF-8
+- The structure of the .csv file is
+  - The first line contains the ABCD field identifiers (e.g. 100,110,....)
+  - Following lines define the data.
+  - A record ends with a lineend, embedded lineends (between "") are allowed
+  - A data cell gives the data of the corresponding field. (may be empty)
+  - All records should have the same number of columns, however less columns as the first line is allowed
+  - ABCD has repeating fields. This program can process the phenomonon in three ways:
+     - Multiple columns with the same tag number are allowed.
+     - Columns of repeated tags (as given by the fdt) are split at delimiter ; (see option -r)
+     - Columns of repeated tags (as given by the fdt) are split at an embedded lineend
+
+### Actions by database administrator
+Most code updates can be excuted by the Upgrade manager.
+
+- The administrator may protect databases by updating dr_path.def. No actions are required if the IP protection is not used.
+- The administrator must copy the executable 'cnv_csv_to_iso' (from https://github.com/ABCD-DEVCOM/ABCD/tree/master/www/cgi-bin_Linux) or 'cnv_csv_to_iso.exe' (from https://github.com/ABCD-DEVCOM/ABCD/tree/master/www/cgi-bin_Windows) to his own cgi-bin.
+

blog/tags.yml

@@ -98,4 +98,8 @@ v3.2.1:
 v3.3.0:
   label: v3.3.0
   permalink: /v3.3.0
-  description: Version 3.3.0 specific posts
+  description: Version 3.3.0 specific posts
+v3.4.0:
+  label: v3.4.0
+  permalink: /v3.4.0
+  description: Version 3.4.0 specific posts

docs/abcd-install/linux-installation.md

@@ -40,7 +40,7 @@ cd /var/www/html
 
 * Example download (always check the GitHub link for the latest version)
 ```bash
-sudo wget https://github.com/ABCD-DEVCOM/ABCD/archive/refs/tags/v3.4.0.zip -O abcd.zip
+sudo wget [https://github.com/ABCD-DEVCOM/ABCD/archive/refs/tags/v3.4.0.zip](https://github.com/ABCD-DEVCOM/ABCD/archive/refs/tags/v3.4.0.zip) -O abcd.zip
 ```
 * Extract
 ```bash
@@ -61,17 +61,20 @@ The package contains folders for multiple operating systems. Clean up what is no
 * Rename `cgi-bin_Linux` to `cgi-bin`.
 
 ```bash
-sudo mv cgi-bin_Linux cgi-bin
+cd /var/www/html/ABCD/www
 ```
 
 
+```bash
+sudo mv cgi-bin_Linux cgi-bin
+```
+
 * Delete `cgi-bin_Windows`.
 
 ```bash
 sudo rm -rf cgi-bin_Windows
 ```
 
-
 2. **Bases:** If this is a clean installation, rename `bases-examples` to `bases`.
 
 ```bash
@@ -88,20 +91,18 @@ ABCD comes with a template configuration file that must be activated.
 cd /var/www/html/ABCD/www/htdocs/central/
 ```
 
-
 2. Copy the template to the actual config file:
 
 ```bash
 sudo cp config.php.template config.php
 ```
 
-
 3. (Optional) Edit `config.php` if you need to change default paths, although the defaults usually work fine if following this guide.
 
 ## 5. Configure Permissions
 
 For ABCD to work (save records, upload images), permissions must be exact.
-👉 **[See the Folder Permissions Guide](/docs/3.1/abcd-install/fixing-permissions-linux)**.
+👉 **[See the Folder Permissions Guide](/docs/abcd-install/fixing-permissions-linux)**.
 
 ## 6. Enable Executables
 
@@ -114,4 +115,32 @@ sudo chmod +x /var/www/html/ABCD/www/cgi-bin/*
 ## 7. Next Steps
 
 * Configure the **Virtual Host** (see sidebar).
-* Access `http://localhost:9090/admin` (or your server IP).
+* Access `http://localhost:9090/admin` (or your server IP).
+
+## 8. Troubleshooting
+
+### OPAC Search Results Not Displaying (Redirecting to Homepage)
+If you can access the OPAC but performing a search redirects you back to the home page instead of displaying the results, your Apache server is likely ignoring the `.htaccess` file. The URL rewriting required by the OPAC will fail without it.
+
+To fix this, especially on **Ubuntu/Debian** systems, you need to allow `.htaccess` overrides in your Apache configuration:
+
+1. Open your main Apache configuration file:
+```bash
+sudo nano /etc/apache2/apache2.conf
+```
+
+2. Scroll down to locate the `<Directory /var/www/>` block.
+
+3. Change the `AllowOverride None` directive to `AllowOverride All`:
+```apacheconf
+<Directory /var/www/>
+	Options Indexes FollowSymLinks
+	AllowOverride All
+	Require all granted
+</Directory>
+```
+
+4. Save the file and restart Apache to apply the changes:
+```bash
+sudo systemctl restart apache2
+```

docusaurus.config.js

@@ -66,9 +66,14 @@ const config = {
 
           versions: {
             current: {
-              label: '3.3.X', // O nome no menu dropdown
-              path: '',       // <--- O TRUQUE: Deixar vazio remove o prefixo da URL
-              banner: 'none', // Remove o aviso de "versão não lançada"
+              label: '3.4.X', 
+              path: '',       
+              banner: 'none',
+            },
+            '3.3': {
+              label: '3.3.x',
+              path: '3.3',
+              banner: 'none',
             },
             '3.2': {
               label: '3.2.x',

versioned_docs/version-3.3/abcd-administration/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Database Architecture and Administration",
+    "position": 6,
+    "link": {
+        "type": "generated-index",
+        "description": "Everything a system administrator needs to know to keep ABCD running."
+    }
+}

versioned_docs/version-3.3/abcd-administration/access-management/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Access Management",
+  "position": 4,
+  "link": {
+    "type": "doc",
+    "id": "index"
+  }
+}

versioned_docs/version-3.3/abcd-administration/access-management/index.md

@@ -0,0 +1,22 @@
+---
+title: Access Management Overview
+sidebar_label: Access Management
+---
+
+# Access Management
+
+Security in ABCD is controlled by a relationship between **Operators** (who logs in) and **Profiles** (what they can do). This section guides administrators through configuring secure access to the system.
+
+## Core Concepts
+
+### 1. Profiles (Authorization)
+Profiles act as templates for permissions. Instead of assigning rights to each user individually, you define a role (e.g., "Cataloger", "Loan Officer") and assign users to that role.
+* **[Manage Profiles](profiles.md)**: Learn how to create and edit permission sets.
+
+### 2. Operators (Authentication)
+Operators are the actual user accounts. Each operator must be assigned to a valid profile to access the system.
+* **[Manage Operators](operators.md)**: Learn how to create users, reset passwords, and restrict access by library branch.
+
+:::tip Security Best Practice
+Avoid using the generic `adm` or `abcd` accounts for daily work. Create individual accounts for every staff member to ensure actions can be traced back to a specific person in the system logs.
+:::

versioned_docs/version-3.3/abcd-administration/access-management/ip-access-control.md

@@ -0,0 +1,84 @@
+---
+title: IP Access Control (dr_path.def)
+sidebar_label: IP Access Control by Database
+sidebar_position: 4
+---
+
+# Database IP Access Control
+
+The ABCD allows you to restrict access to specific databases based on the client's IP address. This is particularly useful for databases that contain sensitive information or resources licensed exclusively for local network use.
+
+**Script:** `inc_ip_check.php`
+**Configuration File:** `bases/[db]/dr_path.def`
+
+## How It Works
+
+When a user attempts to access a database (for example, through `inicio.php`), the system checks the database's directory path definition file (`dr_path.def`) for a specific security parameter called `VALID_IP`.
+
+* **Public Access:** If the `VALID_IP` parameter is not present in the file, the database is public and can be accessed from any IP address.
+* **Restricted Access:** If the parameter is present, the system will block access unless the user's IP matches one of the allowed addresses.
+* **Local Network Exemption:** By design, clients connecting from local network addresses (IPv4 `169.254.x.x` or IPv6 `fe80::`) are always allowed to access the database, bypassing the external IP check.
+
+## Configuration (`VALID_IP`)
+
+To enable this restriction, you must edit the `dr_path.def` file located in the specific database folder.
+
+**File Location:** `bases/[db]/dr_path.def`
+
+You can configure the allowed IPs using a comma-separated list or block all external access completely.
+
+### Examples of Usage
+
+**A. Allow Specific IP Addresses:**
+Add the IPs separated by commas. Only these external IPs (plus the local network) will be granted access.
+```ini
+VALID_IP=192.168.1.100,203.0.113.45,203.0.113.46
+
+```
+
+**B. Block All External Access:**
+If you want the database to be strictly internal and inaccessible to any external IP, use the `none` keyword.
+
+```ini
+VALID_IP=none
+
+```
+
+## Technical & Security Notes
+
+* **Proxy Detection:** The script includes logic to detect the real IP address of the client even if the server is behind a proxy or load balancer. It checks headers such as `HTTP_X_FORWARDED_FOR` and `HTTP_X_REAL_IP` before falling back to `REMOTE_ADDR`.
+* **Enforcement:** The `inc_ip_check.php` script provides the verification logic (returning `true` or `false`). The actual blocking action (showing a warning or denying access) is enforced by the scripts that call this function, such as the search initialization scripts.
+
+---
+
+## How to Configure via UI
+
+You do not need to edit the configuration files manually. The ABCD Central module provides a direct graphical interface to manage these permissions.
+
+**Step-by-Step:**
+1. Log in to the **Central Module** of ABCD.
+2. Select the target database from the main top-left dropdown menu.
+3. On the main menu, click on **Update database definitions**.
+4. Then, select **Advanced database settings (dr_path.def)**.
+5. In the form that opens, ensure you are on the **Database** tab.
+6. Scroll down to the bottom and locate the **Valid IP adresses** field.
+
+![Valid IP Addresses Field](../../media/database-architecture-and-administration/ip-access-control.png)
+
+
+## Configuration Options
+
+In the **Valid IP adresses** field, you can define the access rules using the following formats:
+
+* **Public Access (Default):** Leave the field **empty**. An empty value allows all client addresses to access the database.
+* **Specific External IPs:** Enter valid internet client IPs separated by commas (e.g., `192.168.1.100,203.0.113.45`). Only these specified external addresses will be granted access.
+* **Strictly Local Access:** Enter the word `None`. This blocks all external internet addresses, limiting access solely to local network addresses.
+
+:::info Local Network Exemption
+By design, clients connecting from Link-Local network addresses (IPv4 `169.254.x.x` or IPv6 `fe80::`) are **always allowed**, regardless of the restrictions applied in this field.
+:::
+
+## Technical Notes (Proxy & VPN)
+
+* **Proxy Detection:** The underlying system script (`inc_ip_check.php`) is capable of detecting the real client IP even if your ABCD server is situated behind a proxy, load balancer, or CDN. It automatically checks HTTP headers such as `HTTP_X_FORWARDED_FOR` and `HTTP_X_REAL_IP` to validate the correct origin address.
+* **Rejection Behavior:** If a user accesses the system from an unauthorized IP, the script flags the access as invalid, allowing the calling application (like the OPAC or Central portal) to display a warning and block the visualization of the restricted database.

versioned_docs/version-3.3/abcd-administration/access-management/operators.md

@@ -0,0 +1,53 @@
+---
+title: User Management
+sidebar_label: User Management
+---
+
+# User Management
+
+Effective user management is essential for system security. In ABCD, access control is managed via two interacting components: **Operators** (the people) and **Profiles** (the permissions).
+
+All user data is stored in the `acces` database.
+
+## 1. Access Profiles
+
+Before creating users, you must define what they can do. Profiles act as templates for permissions.
+
+* **Path:** **Central > Administration > User administration > Create/edit profiles**
+
+Instead of assigning permissions to each person individually, you create a profile (e.g., `loan_operator`) and assign it to multiple users. If you update the profile, all associated users are updated instantly.
+
+:::tip Strategy
+Create strict profiles. It is better to have a `cataloger` profile that *only* accesses the Cataloging module than to give everyone the `adm` (Administrator) profile.
+:::
+
+## 2. Managing Operators
+
+Operators are the individual accounts used to log in to the system.
+
+* **Path:** **Central > Administration > User administration > User administration**
+
+### Creating a New Operator
+
+To create a new account, click **New user** and complete the following fields:
+
+#### Essential Fields
+* **Username**: The login ID. Case sensitive (e.g., `maria`). **Avoid spaces or special characters.**
+* **Full name**: The real name of the staff member (e.g., `Maria Silva`).
+* **Profile**: Select the authorization level defined in the previous step.
+* **Password**: Define the initial password.
+* **Confirm password**: Retype to validate.
+
+#### Advanced Configuration
+* **Library Code**: Critical for multi-branch libraries. Restricts the operator to managing copies owned by a specific branch (e.g., `MAIN`, `MED`).
+* **Cataloger Code**: A short code (e.g., `MS`) recorded in the database logs (typically field 900) to audit who created or modified a record.
+* **Expiration Date**: YYYYMMDD format. The account effectively locks after this date. Useful for temporary staff or students.
+
+### Maintenance Tasks
+
+* **Reset Password**: If a user forgets their password, edit their record here. You cannot see the old password (it is encrypted), but you can overwrite it with a new one.
+* **Deactivate User**: To remove access without losing the history of records created by that user, set an **Expiration Date** in the past (do not delete the record unless necessary).
+
+:::danger Security Best Practice
+Never share the generic `abcd` or `adm` accounts. Every staff member must have their own named account to ensure accountability in the system logs.
+:::

versioned_docs/version-3.3/abcd-administration/access-management/profiles.md

@@ -0,0 +1,36 @@
+---
+title: Profiles and Permissions
+sidebar_label: Profiles & Permissions
+sidebar_position: 3
+---
+
+# Profiles and Permissions
+
+In ABCD, permissions are not defined checkbox-by-checkbox for every user. Instead, you define **Profiles** (Roles), and assign users to these profiles.
+
+## How Profiles Work
+A profile is essentially a list of authorized system functions. If a function is not listed in the profile, the menu option will not appear for that user.
+
+Common examples of profiles included by default:
+* **`adm` (System Administrator):** Has access to everything, including file editing and database creation.
+* **`dbadmin` (Database Administrator):** Can manage database structures (FDT/FST) but cannot change system core files.
+* **`operator` (Cataloger):** Can search and edit records but cannot delete databases or change structures.
+* **`loan` (Circulation):** Can only access the Loan module.
+
+## creating or Editing a Profile
+1.  Go to **Administration > User administration**.
+2.  Click on **Create/edit profiles**.
+
+### The Profile Editor
+The editor shows a tree view of all available system functions.
+
+1.  **Select a Profile:** Choose an existing one to edit or type a new name to create one.
+2.  **Grant Permissions:**
+    * Browse the tree structure.
+    * **Check** the boxes for the modules and functions this profile should access.
+    * *Example:* For a "Student Assistant", you might only check **Cataloging > Data Entry** and uncheck everything else.
+3.  **Save:** Click the save button to write the changes to the profile file.
+
+:::tip File Location
+Profiles are physically stored as text files in `bases/par/profiles/`. Advanced users can edit these files directly to create highly granular restrictions.
+:::