Oracle 內建套件 UTL_INADDR：獲取主機名與 IP 位址實戰指南

UTL_INADDR 套件概覽

UTL_INADDR 是 Oracle 提供的網路工具套件，用於在 PL/SQL 中解析**主機名 ↔ IP 位址**，支援本機、區域網路與網際網路環境。

需求權限：`EXECUTE ON UTL_INADDR` (通常授予 PUBLIC)
網路前提：資料庫伺服器具備 DNS 解析能力 / hosts 檔配置正確

核心函數與用法

1. GET_HOST_ADDRESS — 取得 IP 位址

-- 語法
UTL_INADDR.GET_HOST_ADDRESS(host VARCHAR2 DEFAULT NULL) RETURN VARCHAR2

-- 參數為 NULL 時解析本機
-- 失敗拋出例外 (如 ORA-29257: host unknown)

實戰範例

2. GET_HOST_NAME — 取得主機名

-- 語法
UTL_INADDR.GET_HOST_NAME(ip VARCHAR2 DEFAULT NULL) RETURN VARCHAR2

-- 參數為 NULL 時解析本機主機名

實戰範例

進階應用場景

場景一：審計觸發器記錄客戶端真實 IP

CREATE OR REPLACE TRIGGER audit_logon_trg
AFTER LOGON ON DATABASE
DECLARE
  v_client_ip VARCHAR2(45);
  v_host_name VARCHAR2(255);
BEGIN
  -- 從 SYS_CONTEXT 取得客戶端 IP (需啟用 SQLNET.ORA: SQLNET.AUTHENTICATION_SERVICES=(NTS))
  v_client_ip := SYS_CONTEXT('USERENV', 'IP_ADDRESS');
  
  -- 若為 IPv6 或代理 IP，嘗試反解主機名
  BEGIN
    v_host_name := UTL_INADDR.GET_HOST_NAME(v_client_ip);
  EXCEPTION
    WHEN OTHERS THEN
      v_host_name := 'UNRESOLVED';
  END;
  
  INSERT INTO login_audit (username, client_ip, host_name, logon_time)
  VALUES (USER, v_client_ip, v_host_name, SYSDATE);
END;
/

場景二：PL/SQL 發送郵件/HTTP 請求前驗證目標主機可達

CREATE OR REPLACE PROCEDURE check_smtp_reachable(p_host VARCHAR2) IS
  v_ip VARCHAR2(45);
BEGIN
  v_ip := UTL_INADDR.GET_HOST_ADDRESS(p_host);
  DBMS_OUTPUT.PUT_LINE(p_host || ' -> ' || v_ip || ' : DNS 解析正常');
  
  -- 進一步可用 UTL_TCP 嘗試連線埠驗證服務可用性
  DECLARE
    v_conn UTL_TCP.CONNECTION;
  BEGIN
    v_conn := UTL_TCP.OPEN_CONNECTION(v_ip, 25);
    UTL_TCP.CLOSE_CONNECTION(v_conn);
    DBMS_OUTPUT.PUT_LINE('SMTP 埠 25 可連線');
  EXCEPTION
    WHEN OTHERS THEN
      DBMS_OUTPUT.PUT_LINE('SMTP 埠 25 無法連線: ' || SQLERRM);
  END;
EXCEPTION
  WHEN OTHERS THEN
    DBMS_OUTPUT.PUT_LINE('DNS 解析失敗: ' || SQLERRM);
END;
/

場景三：動態配置 Database Link / 外部程式呼叫

-- 根據環境變數動態解析目標主機 IP，避免硬編碼
DECLARE
  v_target_host VARCHAR2(100) := 'api.payment-gateway.com';
  v_ip VARCHAR2(45);
  v_dblink_sql VARCHAR2(500);
BEGIN
  v_ip := UTL_INADDR.GET_HOST_ADDRESS(v_target_host);
  
  -- 動態建立/重建 DB Link (需 CREATE DATABASE LINK 權限)
  v_dblink_sql := 'CREATE OR REPLACE DATABASE LINK payment_gw 
                   CONNECT TO api_user IDENTIFIED BY secret 
                   USING ''(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=' 
                   || v_ip || ')(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ORCL)))''';
  EXECUTE IMMEDIATE v_dblink_sql;
  DBMS_OUTPUT.PUT_LINE('DB Link 已更新至 IP: ' || v_ip);
EXCEPTION
  WHEN OTHERS THEN
    DBMS_OUTPUT.PUT_LINE('失敗: ' || SQLERRM);
END;
/

常見錯誤與排查

ACL 配置範例 (11g+ 必須)

BEGIN
  -- 建立 ACL
  DBMS_NETWORK_ACL_ADMIN.CREATE_ACL(
    acl         => 'utl_inaddr.xml',
    description => 'UTL_INADDR Network Access',
    principal   => 'SCOTT',
    is_grant    => TRUE,
    privilege   => 'resolve');
  
  -- 指派給所有主機 (或特定網段)
  DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL(
    acl  => 'utl_inaddr.xml',
    host => '*');
    
  COMMIT;
END;
/

效能與安全建議

• 快取解析結果：頻繁呼叫時，應用層快取 IP 減少 DNS 查詢負載
• 最小權限原則：ACL 僅授權必要主機/網段，避免 `host => '*'`
• 異常處理：所有呼叫必須包裹 `BEGIN...EXCEPTION...END`，防止單點失敗影響主流程
• IPv6 相容：驗證回傳格式處理邏輯相容 IPv4-mapped IPv6 位址

UTL_INADDR 是資料庫層網路解析的輕量級工具，善用於審計、動態配置、服務健康檢查等場景，但需注意 11g+ ACL 授權與異常處理。