GUIDE TO RUNNING EXTERNAL JOBS ON 10g WITH DBMS_SCHEDULER
NOTE: Users using 11g should use the new method of specifying a credential which eliminates many of the issues mentioned in this note.
This guide covers several common questions and problems encountered when using
dbms_scheduler to run external jobs, either on Windows or on UNIX.
What operating system (OS) user does the job run as ?
External jobs which have a credential (available in 11g) run as the user
specified in the credential. But for jobs without credentials including
all jobs in 10gR1 and 10gR2 there are several cases.
- On UNIX systems, in releases including and after 10.2.0.2 there is a file $ORACLE_HOME/rdbms/admin/externaljob.ora . All external jobs not in the SYS schema and with no credential run as the user and group specified in this file. This should be nobody:nobody by default.
- On UNIX systems, in releases prior to 10.2.0.2 there was no "externaljob.ora" file. In this case all external jobs not in the SYS schema and with no credential run as the owner and group of the $ORACLE_HOME/bin/extjob file which should be setuid and setgid. By default extjob is owned by nobody:nobody except for oracle-xe where it is owned by oracle:oraclegroup and is not setuid/setgid.
- On Windows, external jobs not in the SYS schema and with no credential run as the user that the OracleJobScheduler Windows service runs as. This service must be started before these jobs can run.
- In all releases on both Windows and UNIX systems, external jobs in the SYS schema without a credential run as the oracle user.
What errors are reported in SCHEDULERJOB_RUN_DETAILS views ?
If a job fails, the first place to look for diagnostic information is the SCHEDULERJOB_RUN_DETAILS set of views. In 10gR2 and up the first 200 characters of the standard error stream is included in the additional_info column.
In all releases, the error number returned by the job is converted into a
system error message (e.g. errno.h on UNIX or net helpmsg on Windows) and that
system error message is recorded in the additional info column. If there is no
corresponding message the number is displayed.
In 11g and up the error number returned by the job is additionally recorded in
the error# column. In earlier releases 27369 would always be recorded in the
error# column.
Generic Issues Applicable to UNIX and Windows
- The job action (script or executable) must return 0 or the job run will be marked as failed.
- Always use the full pathname to executables and scripts.
- Do not count on environment variables being set in your job. Make sure that the script or executable that your jobs runs sets all required environment variables including ORACLE_HOME, ORACLE_SID, PATH etc.
- It is not recommended to pass in a complete command line including arguments as the action. Instead it is recommended to pass in only the path to and name of the executable and to pass in arguments as job argument values.
- Scripts with special characters in the execution path or script name may give problems.
- Ensure that the OS user your job runs as has the required privileges/permissions to run your job. See above for how to tell who the job runs as.
- External job actions cannot contain redirection operators e.g. > < >> | && ||
- In general try getting a simple external job working first e.g. /bin/echo or ipconfig.exe on Windows. Also try running the job action directly from the commandline as the OS user that the job will run as.
Windows-specific Issues
- The OracleJobScheduler Windows service must be started before external jobs will run (except for jobs in the SYS schema and jobs with credentials).
- The user that the OracleJobScheduler Windows service runs as must have the "Log on as batch job" Windows privilege.
- A batch file (ending in .bat) cannot be called directly by the Scheduler. Instead cmd.exe must be used and the name of the batch file passed in as an argument. For example
begin
dbms_scheduler.create_job('myjob',
job_action=>'C:\WINDOWS\SYSTEM32\CMD.EXE',
number_of_arguments=>3,
job_type=>'executable', enabled=>false);
dbms_scheduler.set_job_argument_value('myjob',1,'/q');
dbms_scheduler.set_job_argument_value('myjob',2,'/c');
dbms_scheduler.set_job_argument_value('myjob',3,'c:\temp\test.bat');
dbms_scheduler.enable('myjob');
end;
/
- In 10gR1 external jobs that wrote to standard output or standard error streams would sometimes return errors. Redirect to files or suppress all output and error messages when using 10gR1 to run external jobs.
UNIX-specific Issues
- When running scripts, make sure that the executable bit is set.
- When running scripts directly, make sure that the first line of the script in a valid shebang line - starting with "#!" and containing the interpreter for the script.
- In release 10.2.0.1, jobs creating a large amount of standard error text may hang when running (this was fixed in the first 10.2.0.2 patchset). If you are seeing this issue, redirect standard error to a file in your job. This issue has been seen when running the expdp utility which may produce large amounts of standard error text.
- the user that the job runs as (see above section) must have execute access on $ORACLE_HOME/bin and all parent directories. If this is not the case the job may be reported as failed or hang in a running state. For example if your $ORACLE_HOME is /opt/oracle/db then you would have to make sure that
chmod a+rx /opt
chmod a+rx /opt/oracle
chmod a+rx /opt/oracle/db
chmod a+rx /opt/oracle/db/bin
- On oracle-xe, the primary group of your oracle user (if it exists) must be dba before you install oracle-xe for external jobs to work. If you have an oracle user from a regular Oracle installation it may have the primary group set to oinstall.
- On oracle-xe, the extjobo executable is missing so external jobs in the SYS schema will not work properly. This can be fixed by copying the extjob executable to extjobo in the same directory ($ORACLE_HOME/bin).
- Check that correct permissions are set for external job files - extjob and externaljob.ora (see below)
Correct permissions for extjob and externaljob.ora on UNIX
There is some confusion as to what correct permissions are for external job related files.
In 10gR1 and 10.2.0.1 :
- rdbms/admin/externaljob.ora should not exist
- bin/extjob should be setuid and setgid 6550 (r-sr-s---). It should be owned by the user that jobs should run as and by the group that jobs should run as.
- bin/extjobo should have normal 755 (rwxr-xr-x) permissions and be owned by oracle:oraclegroup
In 10.2.0.2 and higher
- rdbms/admin/externaljob.ora file must must be owned by root:oraclegroup and be writable only by the owner i.e. 644 (rw-r--r--) It must contain at least two lines: one specifying the run-user and one specifying the run-group.
- bin/extjob file must be also owned by root:oraclegroup but must be setuid i.e. 4750 (-rwsr-x---)
- bin/extjobo should have normal 755 (rwxr-xr-x) permissions and be owned by oracle:oraclegroup
In 11g and higher
Same as 10.2.0.2 but additionally bin/jssu should exist with root setuid
permissions i.e. owned by root:oraclegroup with 4750 (-rwsr-x---)
Internal Error numbers for UNIX on 10.2.0.2 or 10.1.0.6 or higher
If you are not using a credential and are using version 10.2.0.2 or higher or 10.1.0.6 or higher you may come across an internal error number. Here are the meanings for the internal error numbers.
274661 - can't get owner of or permissions of externaljob.ora file
274662 - not running as root or externaljob.ora file is writable by group or other or externaljob.ora file not owned by root (can't switch user)
274663 - setting the group or effective group failed
274664 - setting the user or effective user failed
274665 - a user or group id was not changed successfully
274666 - cannot access or open externaljob.ora file
274667 - invalid run_user specified in externaljob.ora file
274668 - invalid run_group specified in externaljob.ora file
274669 - error parsing externaljob.ora file
274670 - extjobo is running as root user or group