Skip to content

Commit

Permalink
Reviewed and fixed docs for SuSeFirewallServices.
Browse files Browse the repository at this point in the history 
Note that in most cases a *service* argument needs a "service:" prefix.
Replacing tabs by spaces fixes @example rendering.
  • Loading branch information
@mvidner
mvidner committed Apr 22, 2016
1 parent 9aa9fc4 commit 71ce6bb
Showing 1 changed file with 48 additions and 45 deletions.
93 changes: 48 additions & 45 deletions library/network/src/modules/SuSEFirewallServices.rb
View file
Expand Up @@ -272,8 +272,8 @@ def main
# @return [Boolean] whether service is defined by package
#
# @example
# ServiceDefinedByPackage ("http-server") -> false
# ServiceDefinedByPackage ("service:http-server") -> true
# ServiceDefinedByPackage ("http-server") -> false
# ServiceDefinedByPackage ("service:http-server") -> true
def ServiceDefinedByPackage(service)
service.start_with? DEFINED_BY_PKG_PREFIX
end
Expand All @@ -285,8 +285,8 @@ def ServiceDefinedByPackage(service)
# @return [String] file name (e.g., 'abc')
#
# @example
# GetFilenameFromServiceDefinedByPackage ("service:abc") -> "abc"
# GetFilenameFromServiceDefinedByPackage ("abc") -> nil
# GetFilenameFromServiceDefinedByPackage ("service:abc") -> "abc"
# GetFilenameFromServiceDefinedByPackage ("abc") -> nil
def GetFilenameFromServiceDefinedByPackage(service)
if !ServiceDefinedByPackage(service)
log.error "Service #{service} is not defined by package"
Expand All @@ -299,7 +299,8 @@ def GetFilenameFromServiceDefinedByPackage(service)
# Returns SCR Agent definition.
#
# @return [Yast::Term] with agent definition
# @param string full filename path (to read by this agent)
# @param filefullpath [String] full filename path (to read by this agent)
# @api private
def GetMetadataAgent(filefullpath)
term(
:IniAgent,
Expand Down Expand Up @@ -337,12 +338,13 @@ def GetMetadataAgent(filefullpath)

# Returns service definition.
# See @services for the format.
# If `silent` is not defined or set to `true`, function throws an exception
# SuSEFirewalServiceNotFound if service is not found on disk.
# If *silent* is `false` (the default), the method throws an exception
# {Yast::SuSEFirewalServiceNotFound} if service is not found on disk.
#
# @param [String] service name
# @param [String] service name (including the "service:" prefix)
# @param [String] (optional) whether to silently return nil
# when service is not found (default false)
# @api private
def service_details(service_name, silent = false)
service = all_services[service_name]
if service.nil? && !silent
Expand All @@ -359,6 +361,7 @@ def service_details(service_name, silent = false)
end

# Returns all known services loaded from disk on-the-fly
# @api private
def all_services
ReadServicesDefinedByRPMPackages() if @services.nil?
@services
Expand All @@ -368,6 +371,7 @@ def all_services
# in SuSEfirewall2.
#
# @return [Boolean] if successful
# @api private
def ReadServicesDefinedByRPMPackages
log.info "Reading SuSEfirewall2 services from #{SERVICES_DIR}"
@services ||= {}
Expand Down Expand Up @@ -470,7 +474,7 @@ def ReadServicesDefinedByRPMPackages

# Function returns if the service_id is a known (defined) service
#
# @param [String] service_id
# @param [String] service_id (including the "service:" prefix)
# @return [Boolean] if is known (defined)
def IsKnownService(service_id)
!service_details(service_id, true).nil?
Expand All @@ -480,15 +484,13 @@ def IsKnownService(service_id)
#
# @return [Hash{String => String}] supported services
#
#
# **Structure:**
#
#
# $[ service_id : localized_service_name ]
# $[
# "dns-server" : "DNS Server",
# "vnc" : "Remote Administration",
# ]
# { service_id => localized_service_name }
# {
# "service:dns-server" => "DNS Server",
# "service:vnc" => "Remote Administration",
# }
def GetSupportedServices
supported_services = {}

Expand All @@ -509,6 +511,7 @@ def GetSupportedServices
end

# Returns list of service-ids defined by packages.
# (including the "service:" prefix)
#
# @return [Array<String>] service ids
def GetListOfServicesAddedByPackage
Expand All @@ -517,39 +520,39 @@ def GetListOfServicesAddedByPackage

# Function returns needed TCP ports for service
#
# @param [String] service
# @param [String] service (including the "service:" prefix)
# @return [Array<String>] of needed TCP ports
def GetNeededTCPPorts(service)
service_details(service)["tcp_ports"] || []
end

# Function returns needed UDP ports for service
#
# @param [String] service
# @param [String] service (including the "service:" prefix)
# @return [Array<String>] of needed UDP ports
def GetNeededUDPPorts(service)
service_details(service)["udp_ports"] || []
end

# Function returns needed RPC ports for service
#
# @param [String] service
# @param [String] service (including the "service:" prefix)
# @return [Array<String>] of needed RPC ports
def GetNeededRPCPorts(service)
service_details(service)["rpc_ports"] || []
end

# Function returns needed IP protocols for service
#
# @param [String] service
# @param [String] service (including the "service:" prefix)
# @return [Array<String>] of needed IP protocols
def GetNeededIPProtocols(service)
service_details(service)["ip_protocols"] || []
end

# Function returns description of a firewall service
#
# @param [String] service
# @param [String] service (including the "service:" prefix)
# @return [String] service description
def GetDescription(service)
service_details(service)["description"] || []
Expand Down Expand Up @@ -578,7 +581,7 @@ def GetModified

# Function returns needed ports allowing broadcast
#
# @param [String] service
# @param [String] service (including the "service:" prefix)
# @return [Array<String>] of needed broadcast ports
def GetNeededBroadcastPorts(service)
service_details(service)["broadcast_ports"] || []
Expand All @@ -589,46 +592,46 @@ def GetNeededBroadcastPorts(service)
# Function throws an exception SuSEFirewalServiceNotFound
# if service is not known (undefined).
#
# @param [String] service
# @param [String] service (including the "service:" prefix)
# @return [Hash{String => Array<String>}] of needed ports and protocols
#
# @example
# GetNeededPortsAndProtocols ("service:aaa") -> $[
# "tcp_ports" : [ "122", "ftp-data" ],
# "udp_ports" : [ "427" ],
# "rpc_ports" : [ "portmap", "ypbind" ],
# "ip_protocols" : [],
# "broadcast_ports" : [ "427" ],
# ];
# GetNeededPortsAndProtocols ("service:aaa") -> {
# "tcp_ports" => [ "122", "ftp-data" ],
# "udp_ports" => [ "427" ],
# "rpc_ports" => [ "portmap", "ypbind" ],
# "ip_protocols" => [],
# "broadcast_ports"=> [ "427" ],
# }
def GetNeededPortsAndProtocols(service)
DEFAULT_SERVICE.merge(service_details(service))
end

# Immediately writes the configuration of service defined by package to the
# service definition file. Service must be defined by package, this function
# doesn't work for hard-coded services (SuSEFirewallServices).
# Function throws an exception SuSEFirewalServiceNotFound
# Function throws an exception {Yast::SuSEFirewalServiceNotFound}
# if service is not known (undefined) or it is not a service
# defined by package.
#
# @param [String] service ID (e.g., "service:ssh")
# @param map <string, list <string> > of full service definition
# @param [Hash{String => Array<String>] store_definition of full service definition
# @return [Boolean] if successful (nil in case of developer's mistake)
#
# @see #IsKnownService()
# @see #ServiceDefinedByPackage()
# @see #IsKnownService
# @see #ServiceDefinedByPackage
#
# @example
# SetNeededPortsAndProtocols (
# "service:something",
# $[
# "tcp_ports" : [ "22", "ftp-data", "400:420" ],
# "udp_ports" : [ ],
# "rpc_ports" : [ "portmap", "ypbind" ],
# "ip_protocols" : [ "esp" ],
# "broadcast_ports" : [ ],
# ]
# );
# SetNeededPortsAndProtocols (
# "service:something",
# {
# "tcp_ports" => [ "22", "ftp-data", "400:420" ],
# "udp_ports" => [ ],
# "rpc_ports" => [ "portmap", "ypbind" ],
# "ip_protocols" => [ "esp" ],
# "broadcast_ports"=> [ ],
# }
# )
def SetNeededPortsAndProtocols(service, store_definition)
if !IsKnownService(service)
log.error "Service #{service} is unknown"
Expand Down Expand Up @@ -717,7 +720,7 @@ def SetNeededPortsAndProtocols(service, store_definition)

# Function returns list of possibly conflicting services.
# Conflicting services are for instance nis-client and nis-server.
# DEPRECATED - we currently don't have such services - services are defined by packages.
# @deprecated we currently don't have such services - services are defined by packages.
#
# @return [Array<String>] of conflicting services
def GetPossiblyConflictServices
Expand Down

0 comments on commit 71ce6bb

Please sign in to comment.