.\" Copyright (C) 1994-2018 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" PBS Pro is free software. You can redistribute it and/or modify it under the
.\" terms of the GNU Affero General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or (at your option) any
.\" later version.
.\"
.\" PBS Pro is distributed in the hope that it will be useful, but WITHOUT ANY
.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
.\" FOR A PARTICULAR PURPOSE.
.\" See the GNU Affero General Public License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" For a copy of the commercial license terms and conditions,
.\" go to: (http://www.pbspro.com/UserArea/agreement.html)
.\" or contact the Altair Legal Department.
.\"
.\" Altair’s dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of PBS Pro and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair’s trademarks, including but not limited to "PBS™",
.\" "PBS Professional®", and "PBS Pro™" and Altair’s logos is subject to Altair's
.\" trademark licensing policies.
.\"
.TH pbs_server 8B "19 February 2018" Local "PBS Professional"
.SH NAME
.B pbs_server 
- start a PBS batch server
.SH SYNOPSIS
.B pbs_server 
[-a <active>] 
[-A <acctfile>] 
[-C]
[-d <config path>] 
.RS 11
[-e <mask>] 
[-F <delay>]
[-L <logfile>]
[-M <MoM port>] 
[-N]
[-p <port number>]
[-R <MoM RPP port>] 
[-S <default scheduler port>]
[-s <replacement string>]
[-t <restart type>] 
.RE
.B pbs_server
--version

.SH DESCRIPTION
The
.B pbs_server
command starts a batch server on the local host.
Typically, this command is in a local boot file such as
.I /etc/rc.local.
If the batch server is already in running, 
.B pbs_server
exits with an error.

.B Required Permission
.br
To ensure that the 
.B pbs_server
command is not runnable by the general user community, the server
runs only if its real and effective uid is zero.  You must be root 
on Linux or Admin on Windows.

.SH OPTIONS
.IP "-A <acctfile>" 10
Specifies an absolute path name for the file to use as the accounting file.
If not specified, the file is named for the current date in the
PBS_HOME/server_priv/accounting directory.

.IP "-a <active> " 10
When 
.I True, 
the server is in state "active" and the default scheduler is called
to schedule jobs.
When 
.I False, 
the server is in state "idle" and the default scheduler is not called
to schedule jobs.
Sets the server's 
.I scheduling 
attribute.
If this option is not specified, the server uses the prior 
.I value 
for the 
.I scheduling
attribute.
.br
Format: Boolean
.br

.IP "-C" 10
The server starts up, creates the database, and exits.  Windows only.

.IP "-d <config path>" 10
Specifies the absolute path to the directory containing the server
configuration files, PBS_HOME.  Each server must have a different
configuration directory.  The default configuration directory is
specified in $PBS_HOME, and is typically
.I /var/spool/PBS .

.IP "-e <mask>"
Specifies a log event mask to be used when logging.  See "log_events" in the
pbs_server_attributes(7B) man page.

.IP "-F <delay>"
Specifies the number of seconds that the secondary server should wait 
before taking over when it believes the primary server is down.  If 
the number of seconds is specified as 
.I -1, 
the secondary will make one
attempt to contact the primary and then become active.
.br
Default: 
.I 30 seconds

.IP "-L <logfile>"
Specifies the absolute path name for the log file.
If not specified, the file is named for the current date in the
PBS_HOME/server_logs directory.  PBS_HOME is specified in the $PBS_HOME
environment variable or in /etc/pbs.conf; see the
.I -d
option.

.IP "-M <MoM port>"
Specifies the host name and/or port number on which the server should connect
to MOM.  The option argument,
.I MoM port,
uses the syntax: 
.br
.I \ \ \ [<hostname>][:<port number>]
.br
If 
.I hostname 
is not specified, the local host is assumed.   
.br
If 
.I port number 
is not specified, the default port is assumed.  See the 
.I -M 
option for pbs_mom(8).  
.br
Default: 
.I 15002

.IP "-N" 10
The server runs in standalone mode. On Windows, it does not register
as a Windows service.  On other platforms, MoM does not detach from the 
current session. 

.IP "-p <port number>" 10
Specifies the port number on which the server is to listen for batch requests.
If multiple servers are running on a
single host, each must have its own unique port number.
This option is for use in testing with multiple batch systems on a single host.
.br
Default: 
.I 15001

.IP "-R <MoM RPP port>"
Specifies the port number on which the server should query the up/down
status of MoM.    See the 
.I -R 
option for pbs_mom(8).  
.br
Default: 
.I 15003

.IP "-S <default scheduler port>" 10
Specifies the port number to which the server should connect when
contacting the default scheduler.  The option argument,
.I default scheduler port,
uses the syntax:
.br
.I \ \ \ [<hostname>][:<port number>]
.br
Default: 
.I 15004

.IP "-s <replacement string>" 10
Specifies the string to use when replacing spaces in accounting 
entity names.  Only available under Windows.  See the 
.I PBS Professional Administrator's Guide.

.IP "-t <restart type>"
Specifies behavior when the server restarts.  The
.I restart type
argument is one of the following:
.RS
.IP cold 7
All jobs are purged.  Positive confirmation is required before
this direction is accepted.

.IP create 7
The server discards any existing configuration files: server, nodes, queues,
and jobs, and initialize configuration files to the default values.  
The default scheduler is idled (
.I scheduling 
is set to 
.I False
).  Any multischeds are deleted.

.IP hot 7
All jobs in the Running state are retained in that state.  Any job
that was requeued into the Queued state from the Running state when
the server last shut down is run immediately, assuming the required
resources are available.  This returns the server to the same state as
when it went down.  After those jobs are restarted, normal scheduling
takes place for all remaining queued jobs.  All other jobs are
retained in their current state.

.IP
If a job cannot be restarted immediately because of a missing resource, such
as a vnode being down, the server attempts to restart it periodically for
up to 5 minutes.   After that period, the server will revert to a normal state,
as if 
.I warm 
started, and will no longer attempt to restart any remaining jobs
which were running prior to the shutdown.

.IP updatedb 7
Updates format of PBS data from the previous format to the
data service format.

.IP warm 7
All jobs in the Running state are retained in that state.  All other
jobs are maintained in their current state.  The default scheduler
typically chooses new jobs for execution.  
.I warm 
is the default if 
.I -t
is not specified.


.RE
.LP
.IP "--version" 10
The 
.B pbs_server
command returns its PBS version information and exits.
This option can only be used alone.

.SH FILES
.IP $PBS_HOME/server_priv 10
Default directory for configuration files

.IP $PBS_HOME/server_logs 10
Directory for log files recorded by the server


.SH Signal Handling
When it receives the following signals, the server performs the following actions:

.IP SIGHUP
The current server log and accounting log are closed and reopened.  This 
allows for the prior log to be renamed and a new log started from the time
of the signal.

.IP SIGTERM
Causes a rapid orderly shutdown of 
.B pbs_server, 
identical to 
.I "qterm -t quick".

.IP SIGSHUTDN
On systems where SIGSHUTDN is defined, causes an orderly
.I "quick" 
shutdown of the server.

.IP "SIGPIPE, SIGUSR1, SIGUSR2"
These signals are ignored.
.LP
All other signals have their default behavior installed.

.SH Diagnostic Messages
The server will record a diagnostic message in a log file for any
error occurrence.  The log files are maintained in the server_logs
directory below the home directory of the server.
If the log file cannot be opened, the diagnostic message is written
to the system console.  The server writes its PBS 
version and build information to the logfile whenever it starts up or 
the logfile is rolled to a new file.

.SH Stopping the PBS Server
.B Stopping the Server on Linux
.br
Use the 
.B qterm
command:
.br
.I \ \ \ qterm 
.br
(see qterm(8B)) 
.br
or send a SIGTERM:
.br
.I \ \ \ kill <server PID>

.B Stopping the Server on Windows
.br
if you're running "pbs_server -N" for a standalone mode server,
use:
.br
.I \ \ \ <cntrl>-<break>


.SH EXIT STATUS
.IP Zero
When the server has run in the background and then exits

.IP "Greater than zero"
If the server command fails to begin batch operation


.SH SEE ALSO
The
.I PBS Professional Administrator's Guide
and the following manual pages:
qsub (1B), pbs_connect(3B),
pbs_mom(8B), pbs_sched(8B),
pbsnodes(8B), qdisable(8B), qenable(8B), qmgr(8B), qrun(8B), qstart(8B),
qstop(8B), and qterm(8B)